All APIs exposed through this platform are protected using a two-layer security model:

  1. OAuth 2.0 – Client Credentials (Bearer Token)

  2. Azure API Management Subscription Key

Both are mandatory for every API request.

1. Authentication Overview

Each API call must include:

  • A valid OAuth 2.0 Bearer access token in the Authorization header

  • A valid APIM subscription key in the Ocp-Apim-Subscription-Key header

Requests missing either of these will be rejected.

2. OAuth 2.0 – Client Credentials Grant

Access tokens are issued using the OAuth 2.0 Client Credentials flow.

You will be provided with the following details:

  • Tenant ID

  • Client ID

  • Client Secret

  • Token Endpoint

  • Scope

These credentials uniquely identify your application.

2.1 Token Endpoint

POST https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token

2.2 Request Headers

Content-Type: application/x-www-form-urlencoded

2.3 Request Body

client_id=<YOUR_CLIENT_ID>
client_secret=<YOUR_CLIENT_SECRET>
grant_type=client_credentials scope=<YOUR_SCOPE>

2.4 Token Response

{  
   "access_token": "<JWT_ACCESS_TOKEN>",
   "token_type": "Bearer",
   "expires_in": 3599
}

The returned access_token must be used as a Bearer token when calling APIs.

3. API Subscription Key

In addition to the Bearer token, all API requests must include a subscription key.

A subscription key is issued when you subscribe to an API product. Each subscription provides:

  • Primary Key

  • Secondary Key

The subscription key is used to:

  • Authorize access at the API gateway

  • Enforce rate limits and quotas

  • Track usage and analytics

  • Enable secure key rotation

4. Calling the API

Each request must include both headers.

4.1 Required Headers

Authorization: Bearer <ACCESS_TOKEN>
Ocp-Apim-Subscription-Key: <YOUR_SUBSCRIPTION_KEY>

4.2 Example API Request

POST https://apis.swiipr.com/deep-link

Authorization: Bearer eyJ0eXAiOiJKV1Qi...
Ocp-Apim-Subscription-Key: abcdef123456

5. Token and Key Validity

  • Bearer tokens have a limited lifetime and must be refreshed periodically.

  • Subscription keys do not expire automatically but can be regenerated at any time.

6. Subscription Key Rotation

To rotate a subscription key without downtime:

  1. Update your application to use the secondary key

  2. Regenerate the primary key

  3. Update your application to use the newly generated primary key

  4. (Optional) Regenerate the secondary key

This ensures uninterrupted API access.

7. Common Error Responses

HTTP StatusDescription401 UnauthorizedMissing or invalid Bearer token401 Access DeniedMissing or invalid subscription key403 ForbiddenAccess blocked by policy (IP restriction, etc.)429 Too Many RequestsRate limit or quota exceeded

8. Important Notes

  • Both OAuth token and subscription key are always required.

  • Tokens must be generated using the client credentials provided to you.

  • Subscription keys must be included in every request.

  • Never expose your client secret or subscription keys in client-side code or public repositories.

9. Support

If you experience authentication or authorization issues, please contact support with:

  • API name

  • Timestamp of the request

  • HTTP status code

  • Correlation ID (if available)