Authentication API Reference

Introduction

The Authentication API provides a robust set of endpoints for securely managing user identities and controlling access to your application's resources. It supports industry-standard protocols like OAuth 2.0 and OpenID Connect, ensuring compatibility and best-practice security.

This API allows you to:

• Authenticate users via various methods (e.g., username/password, social logins).
• Issue and validate access tokens.
• Obtain user profile information.
• Manage user permissions and scopes.

Authentication Methods

Our API supports multiple authentication flows to cater to different application types and use cases.

1. Authorization Code Grant Flow

Recommended for server-side applications and single-page applications (SPAs) where the client secret can be kept confidential.

Flow: User is redirected to the authorization server, grants permission, and receives an authorization code, which is then exchanged for an access token.

2. Client Credentials Grant Flow

Used for machine-to-machine interactions where the client is acting on its own behalf, not on behalf of a user.

Flow: The client directly requests an access token from the authorization server using its client ID and client secret.

3. Implicit Grant Flow (Deprecated for new applications)

Used for single-page applications (SPAs) in the past. Not recommended for new development due to security concerns.

Flow: The authorization server directly returns an access token to the client upon successful authorization.

Token Endpoints

These endpoints are used to obtain and refresh authentication tokens.

Obtain Access Token

Use this endpoint to exchange authorization codes or client credentials for access tokens.

POST /oauth/token

Request Body (Authorization Code Grant)

{
  "grant_type": "authorization_code",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "code": "AUTHORIZATION_CODE_FROM_REDIRECT",
  "redirect_uri": "YOUR_REGISTERED_REDIRECT_URI"
}
                

Request Body (Client Credentials Grant)

{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "scope": "read write"
}
                

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN_FOR_LONG_TERM_ACCESS",
  "scope": "read write profile"
}
                

Refresh Access Token

Use this endpoint to obtain a new access token using a refresh token.

POST /oauth/token

Request Body

{
  "grant_type": "refresh_token",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "refresh_token": "YOUR_REFRESH_TOKEN"
}
                

Response

Similar to the "Obtain Access Token" response, but only includes access_token, token_type, expires_in, and potentially an updated scope.

User Info Endpoint

Retrieve information about the authenticated user.

Requires a valid Authorization: Bearer YOUR_ACCESS_TOKEN header.

GET /userinfo

Response

{
  "sub": "auth0|1234567890abcdef12345678",
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "email": "jane.doe@example.com",
  "picture": "https://example.com/jane.jpg",
  "updated_at": "2023-10-27T10:30:00Z"
}
                

Scopes

Scopes define the level of access granted to an application. Users will be prompted to approve these scopes during the authorization process.

Error Handling

The API returns standard HTTP status codes and JSON error responses to indicate issues.

Example Error Response

{
  "error": "invalid_grant",
  "error_description": "Invalid authorization code"
}