Authorization

Introduction to OAuth 2.0

OAuth 2.0 is an industry-standard authorization protocol that allows for greater control over an application’s scope, and authorization flows across multiple devices. OAuth 2.0 allows you to pick specific fine-grained scopes that give you specific permissions on behalf of a user.

Getting started with OAuth 2.0

To enable OAuth 2.0 in your app, please send your redirect URL to [e-mail], so we can whitelist the URL back to your application after login. To test locally, run your application from localhost:3000 which is already whitelisted.

Grant types

We only provide authorization code with PKCE and refresh token as the supported grant types for this initial launch. We may provide more grant types in the future.

Authorization Code Flow

The Authorization Code Flow involves exchanging an authorization code for a token. The authorization code flow with PKCE is great for public clients (e.g., native and single-page applications) because they can't securely store secrets. PKCE introduces a secret created by the calling application that can be verified by the authorization server (Code Verifier).

A basic authorization code flow

Initiate the flow by directing the user to:

https://oauth.vana.com/oauth2/auth
        ?response_type=code
        &client_id=<your_app_client_id>
        &state=<random_state>
        &scope=openid offline
        &redirect_uri=<your_apps_redirect_url>
        &code_challenge=<randomly_generated_code_challenge>
        &code_challenge_method=S256

This URL triggers the user's authentication and consent, returning an authorization code to your specified callback URL.

Scopes

OAuth Scopes is a mechanism in to limit an application's access to your account. An app has to request certain scopes from the user to access those resources. These are the following scopes that can be requested.

Scope	Description
offline	Issues a refresh token which can be used to refresh an access token
openid	Issues an ID token containing the details of the authenticated user
voice:read	Create speech using a user's voice
personality:read	Read the personality description of a user
appearance:read	Create images with the user's likeness
memory:read	Augment chat responses with the user's memory

Token Exchange

Exchange the authorization code for tokens using the token endpoint:

const tokenUrl = "https://oauth.vana.com/oauth2/token"
const tokenRequestBody = new URLSearchParams({
  grant_type: "authorization_code",
  client_id: <your_app_client_id>,
  client_secret: <your_app_client_secret>,
  redirect_uri: <your_apps_redirect_url>,
  code_verifier: codeVerifier,
  code: <authorization_code>,
})
fetch(tokenUrl, {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: tokenRequestBody.toString(),
})
  .then((response) => response.json())
  .then((data) => console.log(data))
  .catch((error) => console.error(error))

This will return an object that contains the access token and an ID token:

{
  "access_token": "ory_at_v8vu1eucN4Iho...xHqQiZmE",
  "expires_in": 3599,
  "id_token": "eyJhbGci...92SBI",
  "refresh_token": "ory_rt_sBUS...F9X5Ac",
  "scope": "openid offline",
  "token_type": "bearer"
}

Utilizing Tokens

• Access Token: Utilize this token to authenticate API calls, ensuring secure access to user data.

• ID Token: Contains information about the user, useful for personalizing user experiences without compromising privacy.

The access token can be saved and used for authenticating your API calls. It should be used in the Authorization: Bearer <token> header.

The ID token can be used to identify the token's subject, which corresponds to the Vana account ID of the user.

{
  "at_hash": "C_1Olp9CnDlYQxoZKL53Dg",
  "aud": [
    "c99509bf-798a-4b94-83ff-048d32742d55"
  ],
  "auth_time": 1701970595,
  "exp": 1701974314,
  "iat": 1701970714,
  "iss": "https://development-oauth.vana.com",
  "jti": "bb804ddd-a0eb-42e7-a1ac-3e270c1ca4a7",
  "rat": 1701970564,
  "sid": "0ebd65ba-2d1c-471f-93fc-8185f1e6f32e",
  "sub": "1e0f53d8-bb10-4429-9cdf-bb4e9962403b" // Vana Account ID
}