Skip to main content

API Keys & Authentication

Updated

⚠️ Before starting, make sure you have reviewed the prerequisites.

This guide explains how to obtain credentials to authenticate with the Read AI API programmatically. The Read AI API uses OAuth 2.1 with dynamic client registration.

We support the Authorization Code grant with refresh tokens for obtaining and renewing access tokens.

To call the API:

  1. Register an OAuth 2.1 client using dynamic client registration.

  2. Obtain an authorization code via the Authorization Code flow.

  3. Exchange the authorization code for access and refresh tokens.

  4. Use the access token to make API requests.

  5. Refresh the access token as needed using the refresh token.

Tip: We recommend appending all curl requests with  | jq .  to get easier to visually parse outputs

Step 1: Register your OAuth client

This first step should be done from a command-line interface using e.g. curl. 

IMPORTANT: Save your client_id and client_secret immediately. The client_secret is sensitive and should be stored securely.

Example API Call

curl -X POST https://api.read.ai/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Analytics Dashboard",
    "redirect_uris": ["https://api.read.ai/oauth/ui"],   
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "scope": "openid email offline_access profile meeting:read mcp:execute",
    "token_endpoint_auth_method": "client_secret_basic"
  }'

You may specify any value you want for client_name but all other details should be left unmodified. 

Example Response

{
  "client_id": "test_id",
  "client_name": "My Analytics Dashboard",
  "client_secret": "super_secret",
  "redirect_uris": ["https://api.read.ai/oauth/ui"],
  "token_endpoint_auth_method": "client_secret_basic",
  "allowed_cors_origins": [],
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "scope": "openid email meeting:read offline_access profile mcp:execute",
  "audience": [
    "https://api.read.ai/v1/meetings",
    "https://api.read.ai/mcp"
  ],
  "registration_client_uri": "https://authn.read.ai/oauth2/register",
  "registration_access_token": "access_token"
}

Remember to save your client_id and client_secret, as these cannot be retrieved again later.

Step 2: Obtain an authorization code

This step happens in a web browser, from the Read AI OAuth page.

Initiate OAuth Flow

Navigate to https://api.read.ai/oauth/ui and:

  • Input your client ID and client secret from your dynamic client registration.
  • The redirect URI should already be filled in correctly as https://api.read.ai/oauth/ui.
  • Click Start OAuth Flow when you are ready to proceed.

Sign In to Read AI

If you are not already logged in to Read AI in your browser, you will then get sent to the Read AI sign in page, where you must sign in with your account.

While all of the SSO options should work, there have been some reports of users not getting automatically redirected back to the OAuth consent screen after logging in. If this happens, you can restart the process at https://api.read.ai/oauth/ui and it should skip the sign in step since you're already authenticated.

Consent Screen

Click Allow Access to consent to all of the scopes being granted to your access token. 

Authorization Code Screen

At this point, you have received your authorization code! In the next step, you'll exchange this code for an access/refresh token pair. The most straightforward way to do this is to click Copy Command which you'll then paste in your CLI.

 

Step 3: Exchange authorization code for tokens

Return back to your command-line interface and run the command you copied at the end of the last step. Make sure to copy and securely save the access_token and refresh_token values.

Example Request

curl -X POST https://authn.read.ai/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic $(echo -n 'REDACTED' | base64)" \
  -d "grant_type=authorization_code" \
  -d "code=REDACTED" \
  -d "redirect_uri=https://api.read.ai/oauth/ui" \
  -d "code_verifier=REDACTED"

Example Response

{
  "access_token": "REDACTED",
  "expires_in": 599,
  "id_token": "REDACTED",
  "refresh_token": "REDACTED",
  "scope": "openid profile email meeting:read mcp:execute offline_access",
  "token_type": "bearer"
}

Step 4: Use the access token to make API calls

You can now use the access token to authenticate requests to the REST API by including it in the Authorization header as a Bearer token.

Example Request

curl -X GET "https://api.read.ai/oauth/test-token-with-scopes" \
  -H "Authorization: Bearer ACCESS_TOKEN"

This is a simple endpoint for testing purposes. For a full listing of available API endpoints and other specification details, see the API Reference page.

Step 5: Refresh the access token as needed

Access tokens expire after 10 minutes and must be refreshed to continue making API requests.

To obtain a new access token, send a request to the OAuth token endpoint using the refresh_token grant.

Important: Refresh tokens are rotated on every use, with a short grace period to help account for concurrency. The token endpoint will return a new refresh token each time you exchange one. You must securely persist the new refresh token and discard the previous one.

Example Request

curl -X POST https://authn.read.ai/oauth2/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -u "CLIENT_ID:CLIENT_SECRET" \
    -d "grant_type=refresh_token" \
    -d "refresh_token=YOUR_REFRESH_TOKEN"

 

Related articles