Authentication

The Haya API uses OAuth 2.0 for authentication and authorisation. This guide explains the correct way to authenticate with the API.

Overview

• Authentication Method: OAuth 2.0 Client Credentials flow
• Token Type: JWT (JSON Web Tokens) with RS256 signing
• Authorisation: Scope-based permissions

Obtaining Credentials

Your OAuth credentials are provided by the Haysto API dev team when you become a partner. You'll receive:

• client_id: A unique identifier for your application
• client_secret: A confidential secret key used to authenticate your application

Secure Storage Recommendations

• Store credentials in environment variables or secure vaults
• Credential rotation available upon request
• Never log or expose client_secret in error messages

Token Endpoint

Requesting an Access Token

Use the token endpoint to obtain an access token for further API requests.

Method	URI
POST	/oauth/token

Request Body

Parameter	Type	Required	Notes
grant_type	string	Yes	Must always be client_credentials
client_id	string	Yes	Your applications client_id
client_secret	string	Yes	Your applications client_secret
scope	string	Yes	The scope which your token must cover

Example Request

curl --location 'https://api.haya-test2.uk/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "scope": "your:required:scope"
}'

Example Response

{
    "token_type": "Bearer",
    "expires_in": 900,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}

Response Body

Parameter	Type	Description
token_type	string	Always Bearer
expires_in	integer	Token lifetime in seconds (900 = 15 minutes)
access_token	string	The token required for followup API requests

Scopes

As a partner, you have access to the following scopes:

Scope	Description
enquiry:referral:create	Access to create case referral data
enquiry:case:intake:create	Access to create cases via the enquiry intake method

Missing scopes

Attempting to access a resource without the required scope will result in an 403 Forbidden response.

{
    "message": "Invalid scope(s) provided."
}

Invalid scopes

Attempting to access a non-existant scope will result in an 400 Bad Request response.

{
    "error": "invalid_scope",
    "error_description": "The requested scope is invalid, unknown, or malformed",
    "hint": "Check the `invalid:scope` scope"
}

Using Access Tokens

Once you have an access token, include it in the Authorization header of all API requests.

Header Format

Authorization: Bearer your_access_token

Example Request

curl --location 'https://api.haysto-v2.test/partners/external/intake' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...' \
--data-raw '{
    ...
}'

Token Lifetime and Caching

• Lifetime: Tokens expire after 15 minutes (900 seconds)
• Caching: It is recommended to use a 30-second buffer to avoid in transit expiration for large requests and minimise token requests.
• Expiration: Upon expiration, a new token can be requested, using the same credentials.
• Refresh: For security reasons, we do not offer long-life refresh tokens.