Authentication

The Eirly REST API uses OAuth 2.0 for secure authentication. This guide covers the authentication flows supported by our authentication service.

Supported Grant Types

1. Client Credentials Flow (For Server-to-Server)

Use this flow for machine-to-machine authentication where no user is involved.

POST https://auth.staging.eirly.health/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

Request Body:

grant_type=client_credentials

Alternative (without Basic Auth header):

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Success Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "encrypted_refresh_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 2592000
}

2. Refresh Token Flow

Exchange a valid refresh token for a new access token when the current one expires.

POST https://auth.staging.eirly.health/oauth/token
Content-Type: application/x-www-form-urlencoded

Request Body:

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN

Success Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "new_encrypted_refresh_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 2592000
}

Using Access Tokens

Include the access token in the Authorization header for all API requests:

GET https://api.staging.eirly.health/v1/referrals
Authorization: Bearer YOUR_ACCESS_TOKEN

Error Responses

Common Error Codes

Code	Type	Description
102	UserNotFound	User account does not exist
108	RefreshTokenInvalid	Refresh token is invalid or expired
109	InvalidGrantType	Unsupported grant type
110	InvalidClientId	Client ID is invalid or not found
111	MissingClientId	Client ID parameter is required
117	AuthorizationTokenNotFound	Authorization token not found
118	AuthorizationHeaderInvalid	Invalid authorization header format
123	InvalidCredentials	Email or password is incorrect

Error Response Format

{
  "error": true,
  "code": "110",
  "type": "InvalidClientId",
  "message": "Invalid client_id"
}

Best Practices

1. Store refresh tokens securely - Use secure storage mechanisms appropriate for your platform
2. Implement token refresh logic - Automatically refresh access tokens before they expire
3. Never expose client secrets - Keep client credentials secure and never commit them to source control
4. Use HTTPS only - All authentication requests must use HTTPS in production

Getting Started

You generate your own client_id and client_secret by enabling API access on your organisation — see the Getting Started guide for the full account → organisation → API key walkthrough.

Once you have credentials:

1. Implement the appropriate OAuth flow for your use case (Client Credentials for server-to-server)
2. Test in the staging environment before going to production

With a token in hand, see the Workflow overview to understand how referral ordering and results delivery fit together before diving into the REST API reference.

For questions or support, please contact the Eirly API team.