The authorization code flow provides access to third-party data. This flow requires explicit permission from that third-party prior to Carta granting you access.

1. Your app redirects your user to Carta where they provide their Carta credentials
2. Carta confirms their credentials and redirects them to your app's callback URI
3. Your app exchanges a temporary token for an OAuth token using Carta's /access_token/ endpoint
4. Your app uses the user’s access token to access Carta's data endpoints

1. Request your user's Carta Identity

Your application redirects the user-agent to Carta’s Authorize URI:

GET https://login.app.carta.com/o/authorize/
    ?response_type=code
    &client_id={CLIENT ID}
    &redirect_uri={REDIRECT URI}
    &scope={SCOPES}
    &state={STATE}

Query Parameters

2. Carta redirects the user back to your site

After the user authorizes your application, Carta redirects the user-agent to the callback URL you specify. The querystring contains two parameters:

code: This is the code you will use in step 3 to exchange for an actual OAuth token.

state: The unguessable string you provided in the state parameter in Step 1.

{REDIRECT URI}?code={AUTHORIZATION CODE}&state={STATE}

The code expires after 60 seconds. If the state we return doesn't match your stored value, abort the process and investigate the cause.

3. Exchange the temporary token for an OAuth token

Your application makes a backend request to exchange this temporary token for an official OAuth token. Calling this endpoint will return the OAuth token:

POST https://login.app.carta.com/o/access_token/

Request Headers

Request Body

Response

{
  "access_token" : {ACCESS TOKEN},
  "expires_in" : {Lifetime in seconds},
  "refresh_token" : {REFRESH TOKEN},
  "scope": {SCOPES REQUESTED},
  "token_type" : 'Bearer',
}

Response Body

4. Use the access token to access the API

The access token allows you to make a request to the API on behalf of the user. Important: Never store the access token or refresh token within a user-agent (e.g. do not store it in a cookie).

Authorization: Bearer <ACCESS TOKEN>
GET https://api.carta.com/<api>

Refresh Token Flow

The refresh token flow allows you to obtain new access and refresh tokens. Access tokens expire after one hour, but you can use this flow to programmatically obtain a new access token without needing reauthorization from the user, at which time you will also receive a new refresh token. Refresh tokens expire after 14 days, after which your application must again request the user to authorize your access to Carta data.

Once a user has granted your organization an authorization code and you have traded that for an initial access/refresh token pair, you are then free to generate new access tokens and refresh tokens without needing end-user intervention, as long as you don’t let the refresh token expire (i.e., wait 14 days).

Make a request for a new token

POST https://login.app.carta.com/o/access_token/

Headers

Request Body

Response Body

{
  "access_token" : {ACCESS TOKEN},
  "expires_in" : {Lifetime in seconds},
  "refresh_token" : {REFRESH TOKEN},
  "scope": {SCOPES REQUESTED},
  "token_type" : 'Bearer',
}

Revoke Token Flow

The revoke token flow lets you revoke an active access token.

Make a request to revoke a token

POST https://login.app.carta.com/o/revoke_token/

Headers

Request Body