Skip to main content

Authentication

OAuth 2.0, scopes, token validation, and agency identity federation.

Authentication

All APIs use OAuth 2.0 bearer tokens. System-to-system integrations use the client credentials grant. In agency deployments, user-facing applications and AI agents use the agency identity provider so calls carry the end user's identity.

Client credentials

  1. Create an application to get a client_id and client_secret.
  2. POST to /oauth/token with HTTP Basic authentication and grant_type=client_credentials.
  3. Send the returned token as Authorization: Bearer <token>. Tokens last one hour; request a new one when it expires rather than storing it long term.
bash
curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope="cases:read" \
  https://dev.ironbrick.us/oauth/token

Scopes

Each operation requires one scope, shown on its reference page. Applications are granted scopes when created; a token can request any subset with the scope parameter. Ask for the least you need.

Token validation

Sandbox tokens are signed JWTs (typ: at+jwt). Resource servers check:

  • Signature from the trusted issuer (sandbox: HS256; agency: RS256 or ES256 with keys published by the IdP).
  • Issuer iss = https://dev.ironbrick.us and audience aud = ironbrick-sandbox.
  • Time: exp, nbf, and iat with at most 30 seconds of clock skew.
  • Client status: the application is active, not revoked, and its secret has not been rotated since the token was issued.
  • Scope includes what the operation requires.

Use the Auth Validator to run these checks interactively, or RFC 7662 introspection from code.

Secret handling

  • Store secrets in a secrets manager or your platform's secure properties, never in source control.
  • Rotate from Applications & keys. Rotation takes effect immediately and invalidates tokens issued with the old secret.
  • Revoke any application you no longer use.

Agency deployments

In production, Iron Brick APIs sit behind the agency API gateway and trust the agency identity provider (for example Login.gov for the public, or Okta or Microsoft Entra ID with PIV/CAC for staff). Options include mutual TLS for system clients, token exchange so AI agents act on behalf of a user, and FIPS 140-validated cryptographic modules for TLS.