Authentication

The Eirly REST API uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) for secure authentication. This guide covers the authentication flows supported by our authentication service.

Supported Grant Types

1. Authorization Code Flow with PKCE (Recommended for User Authentication)

This is the recommended flow for authenticating users in web and mobile applications.

Step 1: Generate Code Verifier and Challenge

// Generate a random code verifier
const codeVerifier = generateRandomString(128);

// Generate code challenge using SHA256
const codeChallenge = base64URLEncode(sha256(codeVerifier));

Step 2: Authorization Request

Direct users to the authorization endpoint:

GET https://auth.eirly.health/auth/authorize

Required Parameters:

• client_id - Your application's client ID
• redirect_uri - Registered callback URL for your application
• code_challenge - Generated code challenge from Step 1
• code_challenge_method - Must be S256
• state - Random string to prevent CSRF attacks
• response_type - Must be code

Example:

https://auth.eirly.health/auth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  code_challenge=GENERATED_CHALLENGE&
  code_challenge_method=S256&
  state=RANDOM_STATE&
  response_type=code

Step 3: Exchange Authorization Code for Tokens

After the user successfully authenticates, they'll be redirected to your redirect_uri with a code parameter. Exchange this code for access and refresh tokens:

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

Request Body:

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&code=AUTHORIZATION_CODE
&redirect_uri=https://yourapp.com/callback
&code_verifier=ORIGINAL_CODE_VERIFIER

Success Response (200 OK):

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

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

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

POST https://auth.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
}

3. Refresh Token Flow

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

POST https://auth.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.eirly.health/v1/referrals
Authorization: Bearer YOUR_ACCESS_TOKEN

Social Authentication

Eirly supports authentication via third-party providers:

• Google OAuth - Sign in with Google
• Apple Sign In - Sign in with Apple

These flows follow the standard OAuth 2.0 authorization code flow with PKCE and integrate seamlessly with the Eirly authentication service.

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
113	RedirectUriMisMatch	Redirect URI doesn't match registered URI
114	AuthorizationCodeFailedVerification	Authorization code verification failed
115	MissingOrUnsupportedCodeChallenge	Code challenge missing or method unsupported
116	PKCEInvalid	PKCE verification failed
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. Always use PKCE - Even for confidential clients, PKCE adds an extra layer of security
2. Store refresh tokens securely - Use secure storage mechanisms appropriate for your platform
3. Implement token refresh logic - Automatically refresh access tokens before they expire
4. Never expose client secrets - Keep client credentials secure and never commit them to source control
5. Use HTTPS only - All authentication requests must use HTTPS in production
6. Validate state parameter - Always validate the state parameter to prevent CSRF attacks

Getting Started

To integrate Eirly authentication into your application:

1. Contact Eirly to register your application and receive a client_id
2. Register your redirect URIs
3. Implement the appropriate OAuth flow for your use case
4. Test in staging environment before going to production

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