SSOGEN / Learn / API Key vs OAuth: One API Call, Two Credentials

Learn

API Key vs OAuth: One API Call, Two Credentials

Choosing between an API key and OAuth means choosing between a long-lived shared secret and a short-lived access token. The token is signed by an authorization server and lists who may call which API with which permissions until when.

A worn brass key on a ring beside a paper ticket and a timer, labelled with the key lifetime and the token scope and exp
A key works until someone revokes it; the token names one API and one scope, and expires on its own.

Both credentials travel in a request header. The API looks up a key in a database, but it can verify a token on its own.

The same call, two credentials

The request is identical. Only the credential line changes, and with it what the server can read.

With an API key
GET /api/v1/reports HTTP/1.1
Host: reports.acme.example
X-API-Key: EXAMPLE-acme-nightly-key-0000
With an OAuth access token
GET /api/v1/reports HTTP/1.1
Host: reports.acme.example
Authorization: Bearer <access token: three base64url parts>
The access token's decoded payload
{
"iss": "https://sso.acme.example",
"sub": "acme-nightly-report",
"client_id": "acme-nightly-report",
"aud": "https://reports.acme.example/api",
"scope": "reports.read",
"iat": 1794992400,
"exp": 1794993300,
"jti": "5d1c0b7e-EXAMPLE"
}

The key is an opaque string. Its meaning sits in the provider’s database. The token carries its own: issued by sso.acme.example, valid only at the reports API, read access only, and expires 900 seconds after issue. RFC 9068 lists these claims for JWT access tokens and uses the client ID as sub when no person is involved.

OAuth vs API key: what each proves, and for how long

A key lives until someone revokes it. A token expires on its own.

API key OAuth access token
What it proves The caller holds a secret issued to some client or project An authorization server granted this client access to one audience, for these scopes
Lifetime Until deleted or rotated, unless the provider sets an expiry Minutes, fixed in exp at issue
Scope Whatever the provider attached to the key record Carried in the token (scope) and limited to one API (aud)
Revocation Delete the key; the next lookup fails Wait for exp, or revoke at the authorization server (RFC 7009) and have the API ask (RFC 7662)
If it leaks Works for anyone, from anywhere, until revoked Works for anyone, only at its audience and scope, until exp

OAuth 2.0 itself (RFC 6749) defines how tokens are issued, not their format. The roles behind the right-hand column are in what is OAuth 2.0.

What the API checks

A key is a database lookup. A token is a signature check plus four comparisons.

  • API key. Hash the presented key and find the stored hash. Read the owner, permissions and quota from that record, then count the call. The server keeps only the hash; the API key generator produces both values.
  • OAuth token. Fetch the issuer’s signing keys from its JWKS address and verify the signature. Check that iss is the expected issuer, aud is this API, exp has not passed and scope covers the call.

The token check needs no call to the issuer per request. That saves a round trip, and it is why a short lifetime matters: a locally checked token stays valid until exp.

When a key is enough

Pick by who is calling and what a leak would cost.

  • Public, read-only data with quotas or billing: API key. OWASP lists keys for stopping API farming and for metered plans, with HTTP 429 when calls come too fast.
  • Internal job calling one low-risk API: Either. A key is simpler. Client credentials add expiry and scope for one extra token request.
  • Sensitive or high-value data: OAuth. OWASP: “Do not rely exclusively on API keys to protect sensitive, critical or high-value resources.”
  • A person lets a third-party app act for them: OAuth. The authorization code grant records the person’s consent and limits it to one app. A key cannot.
  • An AI agent acting for a person: OAuth. The token records the person’s grant and expires on its own.
  • Many APIs, different permissions per caller: OAuth. One issuer mints each token for one audience, named in the resource parameter (RFC 8707).

If a key stays, send it in a header. Google Cloud accepts its key in the key query parameter and warns that this exposes the key “to theft through URL scans”. OWASP adds that keys in URLs end up in web server logs.

Replacing a static key with client credentials

Register the caller once. It then asks for short-lived tokens itself, so no secret sits in a config file for years.

In SSOGEN, the caller becomes a service application under Applications, OpenID Connect, Register service. Its Access step sets which APIs it may call, with which scopes, for how long.

Register service applicationAccess step
Register service application, Access step: audience https://reports.acme.example/api, scope reports.read, 15 minutes
The Access step of the SSOGEN service application wizard, with the audience and scope from the request above.
  • Audiences are required; scopes are optional, and openid, profile and email are refused.
  • Access token lifetime is 5, 15 (default), 30 or 60 minutes.
  • The application proves itself with private key JWT (recommended, public keys only) or a generated client secret shown once and stored by SSOGEN only as a hash.
  • The token response holds access_token, token_type Bearer, expires_in and scope. There is never a refresh token; the job asks again.

A service application has no redirect URI and no assignments, and it is active as soon as it is registered. The service application guide has the token request in curl and Python. For an AI agent that needs owners, expiry, delegation, approvals and kill switches, register it as an AI agent instead. Both run on the SSOGEN OpenID Connect provider.

Questions people ask

Is OAuth the same as an API?

No. OAuth is an authorization framework that controls who may call an API; it is not an API itself. The API exposes data or actions over HTTP, while OAuth (RFC 6749) defines how a client obtains an access token for it. The API checks that token before it answers.

Is OAuth obsolete?

No. OAuth 2.0 is current, and its security guidance was updated in January 2025. RFC 9700, the OAuth 2.0 Security Best Current Practice, tells clients not to use the implicit grant and deprecates other weak modes. OAuth 2.1, which folds that guidance into one specification, is an IETF working-group draft (revision 17, October 2026).

What are the key differences between API keys, JWT, and OAuth?

An API key is an opaque secret, a JWT is a token format, and OAuth is the framework that issues tokens. A JWT (RFC 7519) is signed JSON that a server can verify without a lookup. OAuth access tokens are often JWTs, as profiled in RFC 9068, but OAuth does not require any format.

Is an API key a bearer token?

It behaves like one: whoever holds it can use it. RFC 6750 defines a bearer token as one that any party in possession can use, with no proof of a cryptographic key. OAuth can go further. DPoP (RFC 9449) binds a token to the client’s key, so a stolen copy fails; see DPoP.

Sources, all read 2026-11-18: RFC 6749 (sections 1.4, 2.1, 4.4), RFC 6750 (section 1.2), RFC 7519, RFC 9068, RFC 7009, RFC 7662, RFC 8707, RFC 9700, RFC 9449, draft-ietf-oauth-v2-1 on the IETF Datatracker, OWASP REST Security Cheat Sheet, Google Cloud: use API keys.

Updated