Skip to main content

Subscription keys

The AgencyMax API gateway identifies the calling application with a subscription key. Every request needs a valid subscription key and a valid OAuth access token:

  • The subscription key tells the gateway which application is calling and which product (and therefore which rate limits and quotas) applies.
  • The access token tells the API who is calling, which tenant they belong to and what they're allowed to do.

Getting a key​

  1. Sign in to the API Portal.
  2. Open your Profile to see your subscriptions.
  3. Each subscription has a primary and a secondary key. Either one works.

If you don't have a subscription for the API product you need, contact your AgencyMax representative.

Sending the key​

Send the key in the Ocp-Apim-Subscription-Key header:

GET /agency-management/acme/agents/A1001 HTTP/1.1
Host: api.agencymax.example.com
Ocp-Apim-Subscription-Key: 0123456789abcdef0123456789abcdef
Authorization: Bearer eyJhbGciOi...

The gateway also accepts the key in the subscription-key query string parameter. Don't use it. Query strings end up in logs, browser history and proxies.

Errors​

StatusCause
401 UnauthorizedThe key is missing or invalid, or it belongs to a subscription that doesn't include this API.
403 ForbiddenThe subscription is suspended or cancelled, or its quota is used up.

A gateway rejection never reaches the API, so its body is a simple gateway message, not a problem details document:

{
  "statusCode": 401,
  "message": "Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API."
}

Protecting and rotating keys​

  • Treat subscription keys as secrets. Keep them in a secret store, never in source control, and never ship them in browser or mobile apps.
  • Use the two keys to rotate without downtime:
    1. Switch your application to the secondary key.
    2. Regenerate the primary key in the portal.
    3. Switch back to the new primary key.
    4. Regenerate the secondary key.
  • If you think a key is compromised, regenerate it right away.