Early access: features, availability, and pricing may change as Kyara Intelligence evolves.

Build for your users

Link accounts with OAuth

Let users connect their Kyara account to your app with OAuth 2.1. Your app gets short-lived tokens for the API; users never copy a key.

Kyara Intelligence is an OAuth 2.1 authorization server. A user approves your app once on a Kyara consent page, and your app receives an access token for their account. Requests you send with it run on the user's plan and credits, exactly as their own API key would, on both POST /v1/chat/completions and GET /v1/balance.

Compared with the onboarding flow, nobody copies a key, a leaked access token expires within 15 minutes, and the user can disconnect your app from their account at any time.

Register your app

Open Developer in the dashboard and fill in Register an app:

  • Name: shown to users on the consent page and in their connected apps.
  • Redirect URIs: up to eight, one per line, matched exactly. They must use https. Local callbacks (http on localhost, 127.0.0.1 or [::1]) go in a separate app, never in the production one.

Kyara then shows the client ID and client secret. The secret is shown only once and only a hash of it is stored, so save it in your secrets manager right away. You can register up to 10 apps per account.

Every app is a confidential client that uses the authorization code grant with PKCE, plus refresh tokens. From the Developer page you can also disable an app, which blocks new links and token refreshes until you enable it again, or delete it, which disconnects every user linked through it.

Endpoints

EndpointURL
Authorizationhttps://kyara-intelligence.com/api/auth/oauth2/authorize
Tokenhttps://kyara-intelligence.com/api/auth/oauth2/token
User infohttps://kyara-intelligence.com/api/auth/oauth2/userinfo
Revocationhttps://kyara-intelligence.com/api/auth/oauth2/revoke
Signing keys (JWKS)https://kyara-intelligence.com/api/auth/jwks
Issuerhttps://kyara-intelligence.com/api/auth
Resource (token audience)https://api.kyara-intelligence.com

There is no discovery document, so configure these URLs in your OAuth library directly. The token and revocation endpoints take client credentials through HTTP Basic authentication only (client_secret_basic); a secret sent in the request body is rejected.

Scopes

ScopeWhat it allows
chatRun chat completions on the user's plan and read their balance. Required for any API call.
offline_accessGet a refresh token, so the link outlives the 15-minute access token.
openidGet an ID token identifying the user.
emailRead the user's email address.
profileRead the user's display name.

Authorization flow

  1. Send the user to the authorization endpoint

    Create a PKCE verifier and its S256 challenge (the only method accepted) and a random state, then redirect the user's browser:

    import { createHash, randomBytes } from 'node:crypto';
    
    // Keep the verifier and the state in the user's session until the callback.
    const codeVerifier = randomBytes(32).toString('base64url');
    const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url');
    const state = randomBytes(16).toString('base64url');
    
    const authorize = new URL('https://kyara-intelligence.com/api/auth/oauth2/authorize');
    authorize.search = new URLSearchParams({
      response_type: 'code',
      client_id: process.env.KYARA_CLIENT_ID!,
      redirect_uri: 'https://app.example.com/oauth/callback',
      scope: 'openid email profile offline_access chat',
      state,
      code_challenge: codeChallenge,
      code_challenge_method: 'S256',
      resource: 'https://api.kyara-intelligence.com'
    }).toString();
    
    // Redirect the user's browser to authorize.href

    Always send resource=https://api.kyara-intelligence.com. Without it, the access token is not issued for the API, and every API call with it fails with 401.

  2. The user signs in and approves

    Kyara asks the user to sign in, or to sign up if they have no account, then shows your app's name and the permissions it asks for. When they approve, Kyara redirects to your redirect_uri with a code and your state. Reject the callback if state doesn't match the one you stored.

  3. Exchange the code for tokens

    From your server, post the code and the PKCE verifier to the token endpoint:

    curl https://kyara-intelligence.com/api/auth/oauth2/token \
      -u "$KYARA_CLIENT_ID:$KYARA_CLIENT_SECRET" \
      -d grant_type=authorization_code \
      -d code="$CODE" \
      --data-urlencode redirect_uri=https://app.example.com/oauth/callback \
      -d code_verifier="$CODE_VERIFIER"

    The response carries the tokens and a snapshot of the user's plan:

    {
      "access_token": "eyJhbGciOiJFZERTQSIsInR5cCI6ImF0K2p3dCJ9...",
      "token_type": "Bearer",
      "expires_in": 900,
      "expires_at": 1793004300,
      "refresh_token": "Xk3v9QeL2b...",
      "scope": "openid email profile offline_access chat",
      "id_token": "eyJhbGciOiJFZERTQSJ9...",
      "plan": "lite",
      "plan_status": "active",
      "period_end": "2026-11-25T09:30:00.000Z"
    }
  4. Call the API

    Send the access token as the bearer token, exactly like an API key. With an OpenAI SDK, pass it as apiKey.

    curl https://api.kyara-intelligence.com/v1/chat/completions \
      -H "Authorization: Bearer $ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "deepseek/deepseek-v4-flash",
        "messages": [
          { "role": "user", "content": "Hello!" }
        ]
      }'

Refreshing tokens

Access tokens last 15 minutes. Before one expires, or when the API answers 401, get a new one with the refresh token:

curl https://kyara-intelligence.com/api/auth/oauth2/token \
  -u "$KYARA_CLIENT_ID:$KYARA_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"
  • Every refresh returns a new refresh token; store it in place of the old one before using the new access token.
  • Refresh each user's link from one place at a time, for example behind a lock. If two refreshes overlap, one can fail with invalid_grant even though the other succeeded. Once that refresh has finished, the old token returns the same response for 60 seconds; after that, presenting it again is treated as token theft and revokes the whole link.
  • A refresh token expires 180 days after it was issued, so a link stays alive as long as you refresh within that window.
  • On invalid_grant, reload the stored refresh token first: if another refresh already replaced it, use the new one. If the token you sent is still the latest you have, the link is gone: the user disconnected your app, deleted their account, or the refresh token expired. Drop the stored tokens and ask the user to link again.

Plan information

Every token response, refreshes included, carries the user's subscription, so your app sees plan changes at the next refresh:

FieldMeaning
planlite (Spark), premium (Ember), or null if the user never subscribed.
plan_statusThe subscription status, such as active, trialing, past_due, unpaid or canceled; none without a subscription.
period_endWhen the current billing period ends, as an ISO 8601 timestamp, or null.

plan is reported whatever the status. The API grants the weekly allowance only while the status is active or trialing; otherwise the user's requests run on their top-up credits alone, and return 403 no_active_plan once they have none. See Plans and credits.

To read the same facts between refreshes, use the account field of GET /v1/balance.

To send a user to subscribe, link to https://kyara-intelligence.com/pricing?plan=premium&return=https://app.example.com/billing. plan (lite or premium) highlights that plan. return is where the user lands after checkout or a plan change, instead of their Kyara dashboard: an https URL on the origin of one of your redirect URIs, honored once Kyara has verified your app. Either parameter is ignored otherwise.

Identifying the user

The ID token's sub claim is the user's Kyara ID, stable across links. With the email scope, the ID token also carries email and email_verified. The user info endpoint returns the same details for an access token.

Disconnecting

Users see your app under Connected apps on their account page and can disconnect it there. That deletes their consent and your refresh tokens at once; an access token already issued keeps working until it expires, 15 minutes at most.

When a user unlinks from your side, revoke the refresh token and delete what you stored:

curl https://kyara-intelligence.com/api/auth/oauth2/revoke \
  -u "$KYARA_CLIENT_ID:$KYARA_CLIENT_SECRET" \
  -d token="$REFRESH_TOKEN" \
  -d token_type_hint=refresh_token

Errors

The OAuth endpoints answer in the standard OAuth 2.0 error shape:

{
  "error": "invalid_grant",
  "error_description": "invalid code"
}
errorCommon causes
invalid_clientWrong client ID or secret, credentials sent in the body instead of HTTP Basic, or the app is disabled.
invalid_grantThe code was already used or has expired, the redirect_uri differs from the authorization request, or the refresh token is no longer valid.
invalid_requestA required parameter is missing, such as the PKCE challenge or verifier.
invalid_targetThe resource is not https://api.kyara-intelligence.com.

On the API itself, a missing, expired or invalid access token returns 401 invalid_api_key, like a bad key. See Errors.