Skip to main content

OAuth 2.0

OAuth 2.0 is the authorization framework TraffiTech builds on. It answers the question "is this client allowed to access this resource on behalf of this user (or itself)?" by issuing an access token.

OAuth 2.0 is about authorization. If you also need to know who the user is, use OpenID Connect - it's OAuth 2.0 plus an identity layer on top.

Grant types​

TraffiTech supports four grant types. Pick the one that matches your application's trust model.

GrantWhen to useNotes
Authorization Code + PKCESingle-page apps, mobile apps, native desktop apps - any public client that can't safely store a secretRecommended default for user-facing apps
Authorization Code + Client SecretConfidential web apps with a trusted backend that can hold a secretUse PKCE too where the library supports it
Client CredentialsMachine-to-machine - a backend service calling TraffiTech on its own behalf, with no user involvedGrants an access token for a service account; no refresh token
Refresh TokenRenew an expired access token without re-prompting the userIssued alongside the access token when offline_access is requested

Which grant should I use?​

Your app is a…Grant to use
SPA, mobile app, or native desktop appAuthorization Code + PKCE
Traditional server-rendered web appAuthorization Code + Client Secret (add PKCE)
Backend cron job / internal serviceClient Credentials

Implicit flow and resource owner password credentials are not supported. If you're coming from an older integration that used them, migrate to Authorization Code + PKCE.

Access tokens​

TraffiTech issues access tokens as JWTs signed with the same keys used for ID tokens (published at /jwks). Typical claims:

ClaimMeaning
issIssuer - always https://oidc.traffitech.com
subSubject - the user (for user flows) or the client (for client credentials)
audAudience - the resource the token is intended for
expExpiration (unix seconds)
scopeSpace-separated list of granted scopes
client_idThe client that requested the token

Resource servers that receive a TraffiTech access token should:

  1. Fetch the JWKS from /jwks.
  2. Verify the signature, iss, aud, and exp.
  3. Check that the scope covers the action being performed.

The token endpoint​

All grant types exchange their input (authorization code, refresh token, client credentials) at POST /token:

POST /token HTTP/1.1
Host: oidc.traffitech.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&redirect_uri=...&client_id=...&code_verifier=...

Response:

{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGci...",
  "id_token": "eyJhbGci...",
  "scope": "openid profile email offline_access"
}

The id_token is only returned when the request included the openid scope.

Further reading​