Authorization Code Grant | Rightbrain

OAuth 2.0 Authorization Code Grant

This flow is designed for confidential clients – applications (typically traditional web applications) that run on a server and can securely store a Client Secret. It allows users to grant your application access to their Rightbrain data without sharing their credentials directly with your application.

Use Case: Server-side web applications where the backend can securely handle the Client Secret.

Prerequisites:

You have registered your application in the Rightbrain dashboard.
You have obtained a Client ID and Client Secret.
You have registered one or more Redirect URIs for your application in the dashboard.

Initiate Authorization Request

Redirect the user’s browser to the Rightbrain Authorization Endpoint.
Method: GET
URL: https://oauth.rightbrain.ai/oauth2/auth
Query Parameters:
- response_type=code: Specifies the desired flow.
- client_id=<YOUR_CLIENT_ID>: Your application’s Client ID.
- redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>: The URL where Rightbrain will redirect the user back after authorization. Must match one of the registered URIs.
- state=<OPAQUE_VALUE>: (Recommended) A random string generated by your application to prevent CSRF attacks. You should store this value temporarily (e.g., in the user’s session) to verify it later.
- scope=<SCOPES>: (Optional) A space-separated list of permissions your application is requesting.
  Refresh Tokens
  To receive a refresh token, you must include the offline_access scope in your request.

Example URL (requesting refresh token, broken down):

https://oauth.rightbrain.ai/oauth2/auth?
response_type=code&
client_id=YOUR_CLIENT_ID&
redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback&
state=xyzABC123&
scope=offline_access

Example URL (URL-encoded):

https://oauth.rightbrain.ai/oauth2/auth?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback&state=xyzABC123&scope=offline_access

User Authorizes Application

The user is prompted to log in to Rightbrain (if not already logged in).
The user is shown a consent screen asking them to authorize your application.

Receive Authorization Code

If the user grants authorization, Rightbrain redirects the user’s browser back to your specified redirect_uri.
The redirect URL will include:
- code=<AUTHORIZATION_CODE>: A short-lived, single-use authorization code.
- state=<OPAQUE_VALUE>: The same state value you provided in step 1.
  Verify State Parameter
  Your application must verify that the received state value matches the one stored from step 1 to prevent Cross-Site Request Forgery (CSRF) attacks.

Example Callback URL:

Example Callback URL

https://your-app.com/callback?code=AUTHORIZATION_CODE_HERE&state=xyzABC123

Exchange Authorization Code for Tokens

Your application backend makes a POST request to the Rightbrain Token Endpoint.
Method: POST
URL: https://oauth.rightbrain.ai/oauth2/token
Authentication: Use HTTP Basic Authentication (Client ID as username, Client Secret as password).
Body (Form Data):
- grant_type=authorization_code: Specifies the grant type.
- code=<AUTHORIZATION_CODE>: The code received in step 3.
- redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>: The same redirect URI used in step 1.
- client_id=<YOUR_CLIENT_ID>: Your application’s Client ID.
- client_secret=<YOUR_CLIENT_SECRET>: Your application’s Client Secret.

Example (curl):

Exchange Code for Token

$ CODE="<AUTHORIZATION_CODE_FROM_STEP_3>"
> REDIRECT_URI="https://your-app.com/callback"
> CLIENT_ID="YOUR_CLIENT_ID"
> CLIENT_SECRET="YOUR_CLIENT_SECRET"
> 
> curl -s -X POST \
>   -u "${CLIENT_ID}:${CLIENT_SECRET}" \
>   -H "Content-Type: application/x-www-form-urlencoded" \
>   -d "grant_type=authorization_code" \
>   -d "code=${CODE}" \
>   -d "redirect_uri=${REDIRECT_URI}" \
>   https://oauth.rightbrain.ai/oauth2/token | jq

Receive Tokens

Rightbrain validates the request and responds with a JSON object containing:
- access_token: The token used to make authenticated API calls.
- token_type: Typically Bearer.
- expires_in: The lifetime of the access token in seconds.
- refresh_token: (Optional) Issued only if the offline_access scope was requested and granted. Used to obtain new access tokens without user interaction.

Call the API

Use the obtained access_token in the Authorization: Bearer <access_token> header to make requests to the Rightbrain API on behalf of the user.

Token Refresh

To obtain a new access token using a refresh token, make a POST request to the token endpoint:

Make POST Request

Method: POST
URL: https://oauth.rightbrain.ai/oauth2/token
Authentication: Use HTTP Basic Authentication (Client ID and Secret).
Body:
- grant_type=refresh_token
- refresh_token=<YOUR_REFRESH_TOKEN>
- client_id=<YOUR_CLIENT_ID>
- client_secret=<YOUR_CLIENT_SECRET>