How to Get Your API Token

This is a customer-facing guide to the credentials and tokens Curupira issues, what each one is for, and how to obtain them. "API token" can mean a few different things depending on what you are trying to do — this page disambiguates them.

The three kinds of credential

Credential	What it is	Who uses it	Where it comes from
client_id	Public identifier of your application (a UUID).	Your app, in the authorize request.	Issued when your application is created. Safe to embed.
Application API key	Secret that authenticates a confidential client on the token endpoint (X-API-Key).	Your backend.	Issued with the application; regenerable in the dashboard. Keep secret.
Access / refresh token	Per-user tokens minted by the OAuth flow.	Your app, per logged-in user.	The /oauth2/token endpoint after a user logs in.

:::danger Keep the API key secret The application API key is a server-side secret. Never commit it to source control, embed it in a browser/mobile bundle, or paste it into a client-side config. If it leaks, regenerate it from the admin dashboard (which immediately invalidates the old key). :::

Getting your client_id and API key

Both are created together with your application:

1. Sign in to the admin dashboard at admin.curupira.api.br.
2. Open your tenant → Applications → the application you want.
3. Copy the client_id (UUID) and the API key.
   • The client_id is safe to use in front-end code.
   • The API key is shown for your confidential/back-end use — store it in a secret manager or environment variable.

Regenerating the API key

If the key is compromised or you rotate secrets on a schedule:

1. Application detail page → Regenerate API key.
2. Confirm. The old key stops working immediately.
3. Update the new key everywhere your backend reads it, then redeploy.

Getting a per-user access token

A user access token is the result of the login flow — you do not "request a token" out of band; you run the OAuth2 Authorization Code + PKCE flow and receive tokens for the user who logged in. In short:

1. Redirect the user to /oauth2/authorize (with PKCE + state).
2. Receive the code on your registered redirect URI.
3. Exchange it at /oauth2/token for access_token + id_token + refresh_token.

The complete, copy-pasteable version is in Authentication. A minimal confidential-client exchange:

curl -s -X POST https://auth.curupira.api.br/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-API-Key: $CURUPIRA_API_KEY" \
  -d "grant_type=authorization_code" \
  -d "code=$AUTH_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "client_id=$CURUPIRA_CLIENT_ID" \
  -d "code_verifier=$CODE_VERIFIER"

Using the access token

Send it as a Bearer token to your own APIs and to Curupira's UserInfo endpoint:

curl -s https://auth.curupira.api.br/oauth2/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Your own backend should verify the token (signature against the JWKS, plus iss/aud/exp) before trusting its claims.

Keeping the token fresh

Access tokens expire (default 1 hour). Use the refresh token to get a new set without re-prompting the user — and remember the refresh token rotates on every use, so always save the new one returned in each response:

curl -s -X POST https://auth.curupira.api.br/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "X-API-Key: $CURUPIRA_API_KEY" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$REFRESH_TOKEN" \
  -d "client_id=$CURUPIRA_CLIENT_ID"

FAQ

Can I get a long-lived token for machine-to-machine calls? Curupira's tokens are user-scoped (issued via the interactive login flow). For automating platform administration, use the admin API with an authenticated admin session — see the Admin API Guide. A dedicated client-credentials grant for pure M2M is not part of the current public surface.

I lost my API key — can I retrieve it? No — keys are not shown again after creation for security. Regenerate it in the dashboard and update your backend.

Which host do I call? All protocol + user token operations are on https://auth.curupira.api.br. Administration is on https://admin.curupira.api.br (dashboard) / its API.