Authentication

The Eligibility Engine (EE) API uses OAuth 2.0 for secure authentication and authorisation. This guide explains everything you need to know about authenticating 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
• Access Model: Partner read-only operations

Obtaining Credentials

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

• client_id: A unique identifier for your application (e.g., ee_abc123)
• client_secret: A confidential secret key used to authenticate your application

Keep Your Secret Safe

Your client_secret is sensitive and should be treated like a password. Never expose it in client-side code, commit it to version control, or share it publicly.

Secure Storage Recommendations

• Store credentials in environment variables or secure vaults
• Use separate credentials for staging and production
• Rotate credentials periodically (contact the EE dev team)
• 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 API requests.

Endpoint: POST /oauth/token

Content Types Supported:

• application/json (recommended)
• application/x-www-form-urlencoded (OAuth 2.0 standard)

Request Parameters

Parameter	Type	Required	Description
grant_type	string	Yes	Must be client_credentials
client_id	string	Yes	Your application's client ID
client_secret	string	Yes	Your application's client secret

Example Request (JSON)

curl -X POST https://api.eligibility-engine.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

Example Request (Form-Encoded)

curl -X POST https://api.eligibility-engine.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret"

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJwYXJ0bmVyX2FiYzEyMyIsInNjb3BlcyI6WyJjcml0ZXJpYTpyZWFkIiwibGVuZGVyczpyZWFkIiwicHJvZHVjdHM6cmVhZCJdLCJleHAiOjE3MDk0NzU2MDB9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "criteria:read lenders:read products:read"
}

Response Fields

Field	Description
access_token	The JWT access token to use for API requests
token_type	Always Bearer
expires_in	Token lifetime in seconds (3600 = 1 hour)
scope	Space-separated list of granted scopes

Token Introspection

The introspection endpoint allows you to validate tokens and retrieve their metadata.

Endpoint: POST /oauth/introspect

When to Use Introspection

• Validate that a token is still active
• Check which scopes a token has
• Retrieve token metadata (expiry, partner info)

Example Request

curl -X POST https://api.eligibility-engine.com/oauth/introspect \
  -H "Content-Type: application/json" \
  -d '{
    "token": "your_access_token",
    "token_type_hint": "access_token"
  }'

Response (Active Token)

{
  "active": true,
  "scope": "criteria:read lenders:read products:read",
  "client_id": "ee_abc123",
  "partner_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "partner_name": "Example Partner Ltd",
  "exp": 1709475600,
  "iat": 1709472000
}

Response (Inactive/Expired Token)

{
  "active": false
}

Using Access Tokens

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

Authorization Header Format

Authorization: Bearer your_access_token

Example API Request

curl -X GET https://api.eligibility-engine.com/v1/lenders \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Lifetime and Caching

• Lifetime: Tokens expire after 1 hour (3600 seconds)
• Caching: Cache tokens for their full lifetime to minimise token requests
• Expiry Handling: When a token expires, request a new one with the same credentials
• No Refresh: The Client Credentials flow doesn't use refresh tokens

Token Caching Best Practice

Store the token and its expiry time (expires_in). Request a new token only when the current one is about to expire or has expired.

Partner Scopes

Scopes control which API endpoints you can access. As a partner, you have read-only access through these scopes:

Available Scopes

Scope	Description	Access
criteria:read	Assess eligibility against lender criteria	Read-only access to criteria endpoints
lenders:read	Retrieve lender information and metadata	Read-only access to lender endpoints
products:read	Search and filter mortgage products	Read-only access to product endpoints

How Scopes Work

• Your access token includes all scopes assigned to your partner account
• The Swagger UI dynamically shows only the endpoints available for your scopes
• Attempting to access endpoints without the required scope returns a 403 Forbidden error

Scope Assignment

Scopes are assigned to your partner account by the EE dev team. If you need access to additional capabilities, please contact us.

Error Responses

401 Unauthorized

Returned when authentication fails or the token is invalid/expired.

Example Response:

{
  "detail": "Invalid authentication credentials"
}

Common Causes:

• Missing Authorization header
• Invalid or expired access token
• Malformed token

Solution: Request a new access token using your credentials.

403 Forbidden

Returned when your token is valid but lacks the required scope for the endpoint.

Example Response:

{
  "detail": "Insufficient permissions"
}

Common Causes:

• Accessing an endpoint that requires a scope you don't have
• Attempting write operations (partners have read-only access)

Solution: Check which scopes your token includes and ensure you're only accessing read endpoints.

Troubleshooting

Issue	Solution
Token request fails with 401	Verify your client_id and client_secret are correct
API request returns 401	Check that your token hasn't expired (1 hour lifetime)
API request returns 403	Verify you have the required scope for the endpoint
Token missing scopes	Contact the EE dev team to update your partner account scopes

Detailed Error Information

For complete error response schemas and additional troubleshooting, visit the Swagger UI documentation.

Security Best Practices

Follow these guidelines to keep your API integration secure:

Credential Management

• Never hardcode credentials in your application source code
• Use environment variables or secure configuration management
• Separate staging and production credentials
• Rotate credentials periodically (contact the EE dev team)

Token Handling

• Store tokens securely in memory or encrypted storage
• Never log tokens in application logs or error messages
• Transmit tokens only over HTTPS
• Implement token refresh logic when tokens expire

Network Security

• Always use HTTPS - never make API requests over HTTP
• Validate SSL certificates in production
• Don't expose API responses containing sensitive data client-side

Access Control

• Follow principle of least privilege - only request scopes you need
• Validate responses before processing data
• Implement rate limiting in your application if making high-volume requests

---

Next Steps

Now that you understand authentication:

• Try the API: Head to the Quick Start guide to make your first authenticated request
• Learn capabilities: Read the API Overview to understand what you can do
• Explore endpoints: Visit the Swagger UI for detailed specifications