Authentication

Environments

• Development URL: https://meridian-ai.dev/
• Test URL: https://uat.meridian-ai.dev/
• Production URL: https://app.meridian-ai.com/

OAuth 2.0 Authentication with PKCE

Meridian uses OAuth 2.0 with Proof Key for Code Exchange (PKCE) for secure authentication.

Step 1: Generate a Code Challenge

Generate a code verifier which is then encoded with SHA-256 to produce the code challenge.
You can use tools like PKCE Code Generator.

Step 2: Authorization Request

To authorize a user, make a redirect/GET request to the o/authorize/ endpoint with the following query parameters:

GET o/authorize/
?client_id=<client id>           // provided by Meridian
&response_type=code
&redirect_uri=<url>              // URL where the user will be redirected after authorizing
&code_challenge=<code challenge> // code challenge generated in Step 1
&code_challenge_method=S256

If all data is correct, the user will be redirected to an authorization page. If they are not logged in, they will need to login to the Meridian app first, then confirm the authorization.

Step 3: Exchange Code for Access Token

After the user confirms and clicks Authorize, they will be redirected to the URL specified in the redirect_uri parameter with a code string in the query parameter: ?code=<code>.

Use this code to make a POST request to the o/token/ endpoint to get the access token:

POST o/token/

Request Body:
{
  "grant_type": "authorization_code",
  "code": "<code>",                // the code received from the redirect
  "client_id": "<client id>",      // provided by Meridian
  "client_secret": "<client secret>", // provided by Meridian
  "redirect_uri": "<url>",         // the same redirect URL used in the previous request
  "code_verifier": "<code verifier>" // code verifier used for encoding the code challenge
}

Response Example:

{
  "access_token": "JOLebltHCYdB3YvcW2cPK4bLOi0wzX",
  "expires_in": 36000,            // 10 hours
  "token_type": "Bearer",
  "scope": "read write",
  "refresh_token": "PvCJJIVUlp4tJhDVNor5IIK7TYtO8Y"
}

Use the access_token in the header - Bearer ACCESS_TOKEN to make authenticated requests.
If the user cancels the authorization, they will be redirected back to the same redirect_uri with the query parameter: ?error=access_denied.

Token Refresh

Access tokens have an expiration time (expires_in). Once the access token expires, the client can use the refresh_token to request a new access token without requiring the user to authorize again.

To refresh the token, make a request to o/token/ with the following parameters:

{
  "client_id": "<client id>",
  "client_secret": "<client secret>",
  "refresh_token": "<refresh token>",
  "grant_type": "refresh_token"
}

Authentication Methods

• OAuth 2.0 with PKCE: Primary authentication method
• Session Authentication: Used for web application access
• Kinde Authentication: Used for user management and identity

Authorization

• Fine-grained permissions based on user roles and organization membership
• Organization-based access control for all API resources
• User-specific permissions for private resources