Skip to content
Hantera Developer Portal Developer Portal

Authentication

OAuth authentication is a robust method for securing API requests and managing access tokens. Hantera supports multiple OAuth flows, including the code authorization flow, client credentials, and implicit code grant with PKCE.

Base Path for OAuth Requests

All OAuth-related requests should be directed to the following base path:

/oauth

OAuth Flows

Code Authorization Flow

The code authorization flow is the most commonly used OAuth flow, suitable for web applications where the client can securely store secrets.

  1. Redirect to Authorization Endpoint

    Redirect the user to the authorization endpoint to obtain an authorization code:

    GET /oauth/authorize
    Host: your-hantera-domain.com

    Parameters:

    • response_type: Must be set to code
    • client_id: Your application’s client ID
    • redirect_uri: The URL to redirect the user after authorization
    • scope: The requested permissions (see Scopes)
    • state: A unique string to maintain state between the request and callback

    Example:

    GET /oauth/authorize?response_type=code&client_id=your_client_id&redirect_uri=https://yourapp.com/callback&scope=actors/order:* graph:* me:*&state=unique_state_string

  2. Handle Redirect

    Upon successful authorization, the user will be redirected to your specified redirect_uri with an authorization code and the state parameter:

    https://yourapp.com/callback?code=authorization_code&state=unique_state_string

  3. Exchange Authorization Code for Tokens

    Make a POST request to the token endpoint to exchange the authorization code for an access token and refresh token:

    POST /oauth/token
    Host: your-hantera-domain.com
    Content-Type: application/x-www-form-urlencoded

    Parameters:

    • grant_type: Must be set to authorization_code
    • code: The authorization code received in the callback
    • redirect_uri: The same redirect URI used in the authorization request
    • client_id: Your application’s client ID
    • client_secret: Your application’s client secret

    Example:

    POST /oauth/token
    Host: your-hantera-domain.com
    Content-Type: 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

Client Credentials Flow

The client credentials flow is used for machine-to-machine authentication, where no user interaction is required.

  1. Request Tokens

    Make a POST request to the token endpoint:

    POST /oauth/token
    Host: your-hantera-domain.com
    Content-Type: application/x-www-form-urlencoded

    Parameters:

    • grant_type: Must be set to client_credentials
    • client_id: Your application’s client ID
    • client_secret: Your application’s client secret
    • scope: The requested permissions (see Scopes)

    Example:

    POST /oauth/token
    Host: your-hantera-domain.com
    Content-Type: application/x-www-form-urlencoded
    

    grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret&scope=actors/order:* graph:* me:*

Implicit Code Grant with PKCE

The implicit code grant is available, but mandates the use of PKCE (Proof Key for Code Exchange). This option is useful for clients that can not be trusted with a client secret, such as a PWA or phone app.

  1. Generate a Code Verifier and Challenge

    Generate a secure random string as the code verifier and then create a code challenge using a SHA-256 hash of the code verifier.

  2. Redirect to Authorization Endpoint

    Redirect the user to the authorization endpoint:

    GET /oauth/authorize
    Host: your-hantera-domain.com

    Parameters:

    • response_type: Must be set to code
    • client_id: Your application’s client ID
    • redirect_uri: The URL to redirect the user after authorization
    • scope: The requested permissions (see Scopes)
    • state: A unique string to maintain state between the request and callback
    • code_challenge: The code challenge generated from the code verifier
    • code_challenge_method: Must be set to S256

    Example:

    GET /oauth/authorize?response_type=code&client_id=your_client_id&redirect_uri=https://yourapp.com/callback&scope=actors/order:* graph:* me:*&state=unique_state_string&code_challenge=code_challenge_string&code_challenge_method=S256

  3. Handle Redirect

    Upon successful authorization, the user will be redirected to your specified redirect_uri with an authorization code and the state parameter:

    https://yourapp.com/callback?code=authorization_code&state=unique_state_string

  4. Exchange Authorization Code for Tokens

    Make a POST request to the token endpoint to exchange the authorization code for an access token, including the code verifier:

    POST /oauth/token
    Host: your-hantera-domain.com
    Content-Type: application/x-www-form-urlencoded

    Parameters:

    • grant_type: Must be set to authorization_code
    • code: The authorization code received in the callback
    • redirect_uri: The same redirect URI used in the authorization request
    • client_id: Your application’s client ID
    • code_verifier: The original code verifier used to generate the code challenge

    Example:

    POST /oauth/token
    Host: your-hantera-domain.com
    Content-Type: application/x-www-form-urlencoded
    

    grant_type=authorization_code&code=authorization_code&redirect_uri=https://yourapp.com/callback&client_id=your_client_id&code_verifier=code_verifier_string

Token Lifecycle

  • Access Token: By default, an access token is valid for 60 minutes.
  • Refresh Token: By default, a refresh token is valid for 30 days.

Session Management

A session is created upon a completed authorization and contains both the access and refresh tokens. The first 16 bytes of a token are a UUID that can be used to identify the session.

Revoking Sessions

To revoke a session and disable potentially leaked tokens, use the session revocation endpoint.

POST /oauth/revoke
Host: your-hantera-domain.com
Content-Type: application/x-www-form-urlencoded

Parameters:

  • token: The token to be revoked (either access or refresh token)
  • token_type_hint: A hint about the type of the token being revoked (e.g., access_token or refresh_token)

Example:

POST /oauth/revoke
Host: your-hantera-domain.com
Content-Type: application/x-www-form-urlencoded


token=token_to_be_revoked&token_type_hint=access_token

Personal Access Tokens (PAT)

Personal Access Tokens (PAT) provide a way for users to generate long-living access tokens, with a maximum lifespan of one year. These tokens do not include a refresh token but can be renewed through the /me API.

Creating a Personal Access Token

To create a PAT, use the Portal or the /me API endpoint:

POST /me/pat
Host: your-hantera-domain.com
Content-Type: application/json
Authorization: Bearer your_existing_token
X-Client-Id: <Your client ID>
X-Client-Secret: <Your client secret>

Request Body:

{
  "description": "Your Token Description",
  "scope": "me:* actors:*"
  "expiresAt": "2024-07-01T00:00:00Z" // Max 1 year in the future
}

Response Body:

{
  "keyId": "ed755c9a-05fc-4594-844f-846ef7795336"
  "description": "Your Token Description",
  "issuedAt": "2024-01-01T15:32:34Z",
  "expiresAt": "2024-07-01T00:00:00Z",
  "scope": ["me:*", "actors:*"],
  "active": true,
  "accessToken": "..."
}

Revoking a Personal Access Token

To revoke a PAT, use the /me API endpoint:

DELETE /me/pat/<id>
Host: your-hantera-domain.com
Content-Type: application/json
Authorization: Bearer your_pat

Scopes

Scopes in Hantera are made up of Access Control Entries (ACEs). These define the specific permissions granted to the access token. The format for scopes is typically:

resource/permission

For example:

  • actors/order:*: Grants all permissions on order actors.
  • graph:*: Grants all permissions on the graph.
  • me:*: Grants all permissions on the me resource.

Multiple scopes can be requested by separating them with spaces:

actors/order:* graph:* me:*

Client Identity Management

Client identities are created through the Identity and Access Management (IAM) API. This allows administrators to manage which applications can access the Hantera API and the specific permissions they are granted.

Creating a Client Identity

To create a client identity, use the IAM API to send a POST request with the necessary client details:

POST /iam/clients
Host: your-hantera-domain.com
Content-Type: application/json
Authorization: Bearer your_admin_token

Request Body:

{
  "name": "Your Client Name",
  "redirect_uris": [
    "https://yourapp.com/callback"
  ],
  "grant_types": [
    "authorization_code",
    "client_credentials",
    "implicit"
  ]
}

Restricting Allowed Redirect URLs

Clients can restrict the allowed redirect URLs to enhance security. This is configured during client identity creation by specifying the redirect_uris parameter. Only the URLs listed in redirect_uris will be accepted during the authorization process.

Conclusion

Using OAuth authentication with Hantera ensures secure and controlled access to your resources. By following the steps outlined in this guide, you can implement OAuth flows, manage tokens, handle session revocation, create and manage client identities, and generate Personal Access Tokens effectively. For further details, refer to the Hantera API documentation.