Skip to main content
API guides

Call the API with OIDC instead of an API key

Let your server, function or CI job call the Featurebase API with its platform identity (AWS, Google Cloud, GitHub Actions, GitLab, Kubernetes, Vercel or another OIDC provider) instead of a stored API key.

Your server, function, or CI job can call the Featurebase API without a stored API key. It proves who it is with a short-lived identity token from its platform: AWS, Google Cloud, GitHub Actions, GitLab, Kubernetes, Vercel, or another OIDC provider. Featurebase exchanges that token for an API token that lasts at most 15 minutes.

💡 OIDC API authentication is in beta and available in every workspace.

⚠️ Using Node.js? Do not build this yourself. Use the featurebase-node SDK and copy the code from your connection's Setup screen. The SDK gets, exchanges, caches, and renews tokens for you. Follow Set up with Node.js below and ignore the rest of this page.

Set up with Node.js

  1. Create a connection in Settings → Developers → API → OIDC API authentication.

  2. Install the SDK: npm install featurebase-node. On AWS, also install @aws-sdk/client-sts. On Vercel, also install @vercel/oidc. The Setup screen shows the exact command.

  3. Open the connection's Setup screen and copy the code. It already contains your connection ID.

  4. Run testAuthentication() once from your deployed server. Then use the SDK as usual.

💡 That is all for Node.js. Do not call the token endpoint, cache tokens, or renew them yourself. Vercel works only with Node.js.

Set up with other languages

Use these steps only if your server does not run Node.js.

1

Create a connection

Create a connection in Settings → Developers → API → OIDC API authentication. Copy its connection ID and audience. The audience is https://api.featurebase.app/workloads/<connection ID>. Neither value is a secret.

2

Get an identity token

💡 Using Node.js? Skip this step. The code on your connection's Setup screen already does it.

Request a token for your connection's audience with your platform's own tools:

  • AWS: call STS GetWebIdentityToken with your AWS SDK on a regional endpoint, with SigningAlgorithm: RS256 and DurationSeconds: 900. The account needs outbound identity federation, and the role needs sts:GetWebIdentityToken. AWS guide

  • Google Cloud: read the metadata server's identity endpoint with audience and format=full. Google guide

  • GitHub Actions: request ACTIONS_ID_TOKEN_REQUEST_URL with the audience parameter. The job needs permissions: id-token: write. GitHub guide

  • GitLab CI/CD: add an id_tokens entry with your audience as aud, then read that variable. Keep the job timeout at 60 minutes or less. GitLab guide

  • Kubernetes: mount a projected service account token with your audience and expirationSeconds: 3600. Read the file each time; the kubelet rotates it. Kubernetes guide

  • Other OIDC providers: request a token for your audience from your provider. It needs a public HTTPS issuer with OIDC discovery and a lifetime of one hour or less.

  • Vercel: use Node.js. Vercel provides tokens with a custom audience only through its Node.js package.

3

Exchange the token

⚠️ Using Node.js? Never call this endpoint yourself. featurebase-node does it, including renewal and recovery after a revoked token.

Send one standard OAuth 2.0 token exchange request (RFC 8693). No API key or client secret is needed.

# Not for Node.js: featurebase-node does this for you.
curl https://do.featurebase.app/v1/workload-identities/token \
  --data-urlencode "connection_id=$CONNECTION_ID" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:jwt" \
  --data-urlencode "subject_token=$IDENTITY_TOKEN"

A successful response:

{
  "access_token": "sk_...",
  "token_type": "Bearer",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "expires_in": 900
}

  • 400 invalid_request: Featurebase rejected the identity token or the connection. The connection's Setup screen shows the reason, such as a wrong audience or a claim that does not match. Do not retry at once: wait 5 seconds, and double the wait after each new rejection, up to 5 minutes.

  • 429 or 503 temporarily_unavailable: wait for the Retry-After time, then try again.

4

Call the API and renew

💡 Using Node.js? Skip this step. The SDK adds the token to every request and renews it automatically.

  • Send Authorization: Bearer <access_token> to /v2/ endpoints, the same way as an API key. The token has full API access within your workspace.

  • Keep the token in memory and reuse it. About one minute before expires_in ends, get a new identity token and exchange it again. There is no refresh token.

  • If the API returns 401, or 403 with code: "invalid_api_key", discard the token and exchange once more. If that also fails, the connection is disabled or deleted.

  • Never log either token. Send the API token only to do.featurebase.app.

Troubleshooting

Open the connection's Setup screen and select Check provider and refresh status. It shows the last exchange result and its request ID. Share the request ID with support, never a token.

💡 Node.js: featurebase.testAuthentication() returns the same request ID without exposing a token.

Still need help? Ask the team