Initiate OAuth Authorization

Overview

Initiates the OAuth authorization process and returns a hosted UI URL where users authenticate. This is the first step in the OAuth 2.0 Authorization Code Flow with PKCE (Proof Key for Code Exchange). The redirect_uri provided must be whitelisted in your environment configuration. Authorization sessions expire after 10 minutes, so you must complete the flow before expiration.

When to Use

Starting an OAuth 2.0 authorization flow for third-party access
Implementing secure delegated authentication
Need users to grant permission to your application

PKCE Requirements

PKCE (Proof Key for Code Exchange) is mandatory for security. You must:

Generate code_verifier: 43-128 random characters from [A-Za-z0-9-._~]
Create code_challenge: BASE64URL(SHA256(code_verifier))
Send code_challenge in this request
Store code_verifier securely for use in Step 4 (token exchange)

import crypto from 'crypto';

function generateCodeVerifier() {
  return crypto.randomBytes(32).toString('base64url');
}

function generateCodeChallenge(verifier) {
  return crypto
    .createHash('sha256')
    .update(verifier)
    .digest('base64url');
}

const codeVerifier = generateCodeVerifier();
const codeChallenge = generateCodeChallenge(codeVerifier);

console.log('Store this:', codeVerifier);
console.log('Send this:', codeChallenge);

Flow Types

Hosted UI Flow (Default)

When not using mode=api, this endpoint redirects to a hosted UI where users authenticate:

Call this endpoint to get hosted UI URL (302 redirect or JSON with URL)
Redirect user to hosted UI for authentication
User authenticates and grants permission automatically in UI
User is redirected back to your redirect_uri with authorization code
Exchange authorization code for tokens via POST /v1/auth/oauth/token

API Mode Flow

When using mode=api, you handle authentication in your application:

Call this endpoint with mode=api to get JWT token
Authenticate user via POST /v1/auth/login to get access token
Call POST /v1/auth/oauth/authorize with both tokens to obtain authorization code
Exchange authorization code for tokens via POST /v1/auth/oauth/token

Request

Query Parameters

client_id

string

required

Your public API client key (same as x-client-key header)Format: UUIDExample: 100a99cf-f4d3-4fa1-9be9-2e9828b20ebb

response_type

string

required

Must be code (authorization code flow only)Allowed values: code

redirect_uri

string

required

Your callback URL where user will be redirected after authorizationMust be whitelisted in environment settingsExample: https://yourapp.com/callback

state

string

required

CSRF protection token. Client-defined random string returned unchanged in callbackMinimum length: 8 charactersVerify this matches your original value when receiving the callbackExample: random_csrf_protection_string_12345

code_challenge

string

required

PKCE code challenge. BASE64URL(SHA256(code_verifier))Pattern: 43-128 characters from [A-Za-z0-9-._~]Example: M5iYUROLfJajkMMUkn3gpEquAVQpnK4m55NCeK40nls

code_challenge_method

string

required

PKCE challenge method. Must be S256 (SHA256 hashing)Allowed values: S256

client_secret

string

Client secret key - only required if secret key is issued for your environmentExample: 100a99cf-f4d3-4fa1-9be9-2e9828b20eaa

region

string

Set to us to route requests to the US backend environment (if available for your client)Allowed values: usDefault: international environment

mode

string

Set to api to return JSON instead of 302 redirect. Useful for API-only integrationsAllowed values: api

Headers

x-client-key

string

required

Your public API client key

x-secret-key

string

Your secret API key (required only if secret key is issued)

Response

token

string

JWT session token (valid for 10 minutes) - only returned when mode=apiFormat: JWTExample: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

url

string

Hosted UI URL where user should authenticateFormat: URIExample: https://app.example.com/account/login?token=eyJhbGc...

Success Responses

200 OK (API Mode)
302 Found (Default)

Returned when: mode=api parameter is provided

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "url": "https://app.example.com/account/login?token=eyJhbGc..."
}

Returned when: Default behavior (no mode parameter)Redirects to: Hosted UI URLLocation header: https://app.example.com/account/login?token=eyJhbGc...

Error Responses

400 Bad Request - Invalid Parameters

{
  "error": "invalid_request",
  "error_description": "PKCE is required. Missing code_challenge or code_challenge_method parameter"
}

Common causes:

Missing or invalid PKCE parameters
Invalid response_type (must be code)
Missing required parameters (client_id, redirect_uri, state)
Invalid parameter formats

422 Validation Error

{
  "message": "redirect_uri is not allowed"
}

Common causes:

redirect_uri not whitelisted in environment configuration
Invalid URL format
Parameter validation failures

429 Too Many Requests

{
  "error": "invalid_request",
  "error_description": "Too many authorization requests. Please try again later."
}

Cause: Rate limit exceeded. Wait before retrying.

498 Invalid Client Key

{
  "message": "Invalid client key"
}

Cause: The x-client-key header contains an invalid or unknown key.

499 Missing Client Key

{
  "message": "Missing client key"
}

Cause: The required x-client-key header is missing.

Code Examples

curl -X GET "https://dev.api.baanx.com/v1/auth/oauth/authorize/initiate?client_id=100a99cf-f4d3-4fa1-9be9-2e9828b20ebb&response_type=code&redirect_uri=https://yourapp.com/callback&state=random_csrf_protection_string_12345&code_challenge=M5iYUROLfJajkMMUkn3gpEquAVQpnK4m55NCeK40nls&code_challenge_method=S256" \
  -H "x-client-key: 100a99cf-f4d3-4fa1-9be9-2e9828b20ebb"

Edge Cases and Important Notes

Session Expiration: Authorization sessions expire after 10 minutes. If your user doesn’t complete authentication within this window, you must restart the flow from Step 1.

Redirect URI Whitelist: The redirect_uri parameter MUST be whitelisted in your environment configuration. Contact your account manager to add URIs to the whitelist.

State Parameter Security: Always verify the state parameter returned in the callback matches the one you sent. This prevents CSRF attacks.

PKCE Code Verifier Storage

The code_verifier must be stored securely and retrieved during token exchange (Step 4):

Web apps: Use sessionStorage or secure session cookies
Mobile apps: Use secure device storage (Keychain on iOS, Keystore on Android)
Server-side apps: Store in secure session or database with expiration

Multiple Simultaneous Sessions

Each authorization session is independent. You can have multiple concurrent sessions with different state values, but each requires its own PKCE pair.

Rate Limiting

The endpoint implements rate limiting to prevent abuse. If you receive a 429 error, implement exponential backoff:

async function initiateWithRetry(maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await initiateOAuth();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i)));
        continue;
      }
      throw error;
    }
  }
}

Next Steps

After initiating authorization:

Step 2: User Authentication

If using API mode, authenticate the user to get an access token

Step 3: Generate Authorization Code

Generate the authorization code using the JWT token

Step 4: Token Exchange

Exchange the authorization code for access and refresh tokens

​Overview

​When to Use

​PKCE Requirements

​Flow Types

​Hosted UI Flow (Default)

​API Mode Flow

​Request

​Query Parameters

​Headers

​Response

​Success Responses

​Error Responses

​Code Examples

​Edge Cases and Important Notes

​PKCE Code Verifier Storage

​Multiple Simultaneous Sessions

​Rate Limiting

​Next Steps

Step 2: User Authentication

Step 3: Generate Authorization Code

Step 4: Token Exchange

​Related Documentation

Overview

When to Use

PKCE Requirements

Flow Types

Hosted UI Flow (Default)

API Mode Flow

Request

Query Parameters

Headers

Response

Success Responses

Error Responses

Code Examples

Edge Cases and Important Notes

PKCE Code Verifier Storage

Multiple Simultaneous Sessions

Rate Limiting

Next Steps

Related Documentation