Authentication
How consumers authenticate to APIs behind the gateway.
Most APIs behind the gateway take an API key, which you request and manage in the Developer Portal. Some also ask for a second credential alongside it.
API keys (key-auth)
The default for most APIs. You request a key from the API's portal page, for one environment; the portal issues it as a Kong key-auth credential for that API. Send it on every request:
curl https://api.internal/v1/resource \
-H "apikey: $API_KEY"Keys are tied to your identity and can be revoked by the producer or platform team.
Use a key only for the API it was issued for. Each API gets its own access list the next time its owner deploys it: from then on it refuses (403) every key issued for another API. Until then a key may also work on other APIs on the same gateway; don't build on that. A key issued before the portal started issuing one key per API may be refused once the API has its access list: if a key that used to work starts returning 403, ask the API's owner, who can tell you whether to request a new one.
Careful — the header name. The gateway checks the header configured on its key-auth plugin (default
apikey), which is what the "Try it" console and the examples here use. An API's spec may declare a different scheme header (commonlyX-API-Key) — that describes how the backend expects to be called, not the gateway. Sending the spec's header to the gateway returns401 No API key found in requesteven with a perfectly valid key.
Which keys you can see and use
The console's key picker lists the keys you requested yourself. A producer of the API sees every consumer's keys on their side. A key a producer issues for you directly is recorded as the producer's own request, not yours, so it does not appear in your picker. It still works: paste it into the console's credential field or send it yourself.
A second credential (JWT, OAuth 2.0, client certificate)
Some APIs ask for a JWT, an OAuth 2.0 access token or a client certificate as well as the API key. The portal issues API keys only: get the other credential from the API's owner, and send both:
curl https://api.internal/v1/resource \
-H "apikey: $API_KEY" \
-H "Authorization: Bearer $ACCESS_TOKEN"On an API that has its access list, a route whose authentication has no API key refuses every caller (403), whatever else you send, and so do some combinations of an API key with another method. If calls are refused with a valid key, ask the API's owner.
A Microsoft Entra ID token
Some APIs also take a Microsoft Entra ID access token, on top of the API key. The gateway checks the token's signature, issuer, expiry and audience, then the app roles or scopes the operation requires. The API's page says which: a Microsoft Entra ID token panel names the tenant, the audience and who calls (an app or a signed-in user), and each operation that needs a token lists its roles or scopes.
You get the token from Entra, not from the portal:
-
Your app calls the API itself (callers: apps). Register your app in Entra and ask the API's owner to grant it the app roles the operations list; they may also have to add your app to the API's allowed calling apps. Then get a token with the client credentials grant:
curl -X POST "https://login.microsoftonline.com/$TENANT/oauth2/v2.0/token" \ -d grant_type=client_credentials \ -d client_id="$CLIENT_ID" \ -d client_secret="$CLIENT_SECRET" \ -d "scope=$AUDIENCE/.default" -
Your app calls on behalf of a signed-in user (callers: users). Your app signs the user in (authorization code flow) and asks for the scopes the operations list, on the API's audience.
Send the token with the key:
curl https://api.internal/v1/resource \
-H "apikey: $API_KEY" \
-H "Authorization: Bearer $ACCESS_TOKEN"A missing or expired token is a 401, and so is a token sent anywhere but the
Authorization header. A token for another audience is refused with a 401 or a 403. A
token without the role or scope, or from an app the API doesn't allow, is a 403. In "Try
it", paste the token into the Microsoft Entra ID token field (or Swagger's
Authorize dialog), next to the key.
Which one does my API use?
Each API's catalog page shows its auth type (API Key, JWT or OAuth 2.0), and the Microsoft Entra ID token panel when it takes one. The interactive reference in the Developer Portal lets you try calls with your credential pre-filled.
Your key is shown once
The portal shows a key in full one time: straight after your request when it is issued at once, or when you click Reveal key on your API keys page after an approval. Store it then. After that the page shows only its last four characters, and nobody can look it up for you. A key you don't reveal within 7 days is erased (Not collected in time); your access itself stays.
Lost it, or never collected it? Click Regenerate key on its row. You get a new key for the same API and environment, again shown once. Depending on the portal it is shown straight away, or the row reads New key requested and the key appears there shortly as Ready, not yet viewed: reveal it and store it.
The old key keeps working until it is revoked, so nothing breaks while you switch over:
- Where the new key is shown straight away, Revoke the old key now is ticked for you. Leave it ticked if the key is lost or someone else may have seen it.
- Where the new key arrives in the list, the dialog that shows it asks when an old key is still listed: choose I've stored it, revoke the old key, or keep the old key for now while an application switches over. If the dialog does not ask and you regenerated because a key was lost or leaked, contact support to have the old key checked.
- Either way, Revoke old key on the row revokes it whenever you choose.
If no new key arrives, the page tells you: regenerate again.
Rotating and revoking
Rotate keys regularly with Regenerate key. If a key is compromised, regenerate it and revoke the old one, or revoke your access from the portal — the gateway stops honouring it immediately.