Authentication API

Complete reference for OAuth 2.0 and OpenID Connect authentication endpoints.

Base URL

https://auth.oauth42.com

All authentication endpoints are prefixed with this base URL. Ensure all requests use HTTPS.

Authorization Endpoint

GET/oauth/authorize

Initiates the OAuth 2.0 authorization code flow. Redirects user to login page, then back to your application with an authorization code.

Query Parameters

client_idrequired

Your application's client ID from the OAuth42 dashboard.

redirect_urirequired

URL where user will be redirected after authorization. Must exactly match a registered redirect URI.

response_typerequired

Must be code for authorization code flow.

scopeoptional

Space-separated list of scopes. Example: openid profile email

staterecommended

Random string to prevent CSRF attacks. Returned unchanged in callback.

code_challengerequired

PKCE code challenge. Base64-URL encoded SHA256 hash of code verifier.

code_challenge_methodrequired

Must be S256 for SHA256 hashing.

nonceoptional

Random string included in ID token for replay attack prevention (OpenID Connect).

Example Request

GET /oauth/authorize?
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=openid+profile+email&
  state=random_state_string&
  code_challenge=CODE_CHALLENGE&
  code_challenge_method=S256&
  nonce=random_nonce_string

Success Response

User is redirected to redirect_uri with authorization code:

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?
  code=AUTHORIZATION_CODE&
  state=random_state_string

Error Response

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?
  error=invalid_request&
  error_description=Missing+required+parameter&
  state=random_state_string

Token Endpoint

POST/oauth/token

Exchanges authorization code for access token, or refreshes an access token.

Authorization Code Grant

Exchange authorization code for tokens:

Request Body (application/x-www-form-urlencoded)

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://yourapp.com/callback&
client_id=your_client_id&
client_secret=your_client_secret&
code_verifier=CODE_VERIFIER

Success Response (200 OK)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_token_string",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile email"
}

Refresh Token Grant

Obtain new access token using refresh token:

Request Body

grant_type=refresh_token&
refresh_token=REFRESH_TOKEN&
client_id=your_client_id&
client_secret=your_client_secret

Success Response (200 OK)

{
  "access_token": "new_access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "new_refresh_token",
  "scope": "openid profile email"
}

Client Credentials Grant

Machine-to-machine authentication (no user context):

Request Body

grant_type=client_credentials&
client_id=your_client_id&
client_secret=your_client_secret&
scope=api:read api:write

Success Response (200 OK)

{
  "access_token": "client_access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api:read api:write"
}

Revoke Token

POST/oauth/revoke

Revoke an access token or refresh token, invalidating it immediately.

Request Body

token=TOKEN_TO_REVOKE&
token_type_hint=access_token&
client_id=your_client_id&
client_secret=your_client_secret

token_type_hint can be:

  • access_token - Revoke access token
  • refresh_token - Revoke refresh token (also revokes all associated access tokens)

Success Response (200 OK)

{
  "success": true,
  "message": "Token revoked successfully"
}

Token Introspection

POST/oauth/introspect

Validate and get metadata about an access token.

Request Body

token=ACCESS_TOKEN&
client_id=your_client_id&
client_secret=your_client_secret

Success Response (200 OK)

{
  "active": true,
  "scope": "openid profile email",
  "client_id": "your_client_id",
  "username": "[email protected]",
  "token_type": "Bearer",
  "exp": 1735689600,
  "iat": 1735686000,
  "sub": "user_12345",
  "aud": "your_client_id"
}

Inactive Token Response

{
  "active": false
}

UserInfo Endpoint

GET/oauth/userinfo

Get user information claims using an access token (OpenID Connect).

Request Headers

Authorization: Bearer ACCESS_TOKEN

Success Response (200 OK)

{
  "sub": "user_12345",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "email": "[email protected]",
  "email_verified": true,
  "picture": "https://example.com/avatar.jpg",
  "updated_at": 1735686000
}

Claims returned depend on the scopes requested during authorization.

Logout

POST/oauth/logout

End the user's session and revoke all associated tokens.

Request Body

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN"
}

Success Response (200 OK)

{
  "success": true,
  "message": "Logged out successfully"
}

MFA Challenge

POST/oauth/authorize/mfa

Complete MFA challenge when multi-factor authentication is required.

Request Body

{
  "mfa_token": "TEMPORARY_MFA_TOKEN",
  "code": "123456"
}

Or use a backup code:

{
  "mfa_token": "TEMPORARY_MFA_TOKEN",
  "backup_code": "1234-5678"
}

Success Response

Redirects to redirect_uri with authorization code:

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?
  code=AUTHORIZATION_CODE&
  state=random_state_string

Error Codes

invalid_request

The request is missing a required parameter or has invalid parameter values.

invalid_client

Client authentication failed (invalid client_id or client_secret).

invalid_grant

The authorization code or refresh token is invalid, expired, or revoked.

unauthorized_client

The client is not authorized to use this grant type.

unsupported_grant_type

The grant type is not supported by the authorization server.

invalid_scope

The requested scope is invalid, unknown, or malformed.

access_denied

The user or authorization server denied the request.

mfa_required

Multi-factor authentication is required. Use the provided mfa_token to complete the challenge.

Next Steps

Management API

User and client management endpoints

OAuth 2.0 Overview

Learn about OAuth 2.0 concepts and flows

Quickstart Guide

Get started with your first integration