OAuth and identity

Two different things live under /oauth. GET /oauth/userinfo is an ordinary API operation: it answers with the identity behind whatever credential you send, and every credential can call it. Everything else on this page is the authorization flow that issues an OAuth access token in the first place: discovery, client registration, consent, code exchange, refresh, revocation.

That flow is how nima's MCP consent works. Connecting Claude to https://mcp.getnima.io/mcp runs exactly these steps, which is why there is no client id or secret to paste. See Connect to nima's MCP server.

You can run the same flow from a client you write. It is the alternative to a personal API key for an interactive app: each person approves their own access in a browser, your app stores a token instead of their key, and the access ends when your app revokes the token (for example on sign-out), when the person leaves the workspace, or 30 days after the last refresh. nima has no screen where a person can list or revoke the apps they approved.

The flow runs in five steps:

1. Read the discovery documents to learn the endpoints.
2. Register a client and keep the client_id.
3. Send the person to /oauth/authorize. They sign in and approve.
4. Exchange the code they come back with for an access and refresh token.
5. Refresh once an hour, for as long as the connection lives.

OAuth and identity operations

/mcp is the resource an OAuth access token is issued for. The MCP server endpoint section documents its methods, protocol versions and message rules.

None of the paths on this page carry a /v1 segment. Most of the rest of the API does. Use each path exactly as printed.

/oauth/register, /oauth/token and /oauth/revoke allow 15 requests per 30 seconds (the hard tier, the strictest of the API's shared tiers). Everything else on this page allows 100 per minute. See Rate limits.

Read the identity behind a credential

Read the authorization server metadata

Read the protected resource metadata

Register an OAuth client

Send the person to the OAuth consent screen

Send a non-empty state. It is forwarded to the consent screen and required there, so an empty one does not fail at /oauth/authorize. It fails at the moment the person clicks Allow, which is the worst place to find out.

The token can be narrower than the screen

The consent screen lists what the client asked for. The token carries that minus anything the approver's own role cannot back, with no error and no note on the screen. If nothing survives, for example a request for sources:read alone approved by a member, Allow fails on the screen and no code is issued. sources:read needs owner or admin, so when a member approves, the token comes back without it and get_signal_source answers 403 for the life of that token.

Read scope in the token response. It is the answer, not the request.

Exchange the code for tokens

Refresh an access token

Revoke an OAuth token

The userinfo identity object

What GET /oauth/userinfo answers with.

The token object

What both grants on POST /oauth/token answer with.

Scopes an OAuth client can hold

An OAuth client can hold exactly the 8 consent scopes. The table lists them in registration order (the order of scopes_supported), with the label the person sees and what each unlocks. The consent screen shows the read scopes first, then the two write scopes.

subscriptions:write is broader than it sounds: saved watches and scheduled messages run AI tasks with the owner's workspace context.

Those names are the MCP tools; each one is an HTTP operation as well, and every operation in this reference names the scope it needs. See Knowledge tools, Pipeline tools and Watch tools for the tool reference.

GET /oauth/userinfo accepts a token holding any one of the 17 grantable scopes, which is why every API key and every access token can call it.

A token's scopes are checked on every call, and its permissions are narrowed again by the approver's role at that moment, so a token issued to an admin who is later demoted quietly loses reach without changing. Authentication has the full rule and the nine scopes an OAuth client cannot hold.

Use an OAuth access token on API calls

The same header as an API key, and the same treatment from there on.

curl -s "https://api.getnima.io/v1/signals?limit=20" \
  -H "Authorization: Bearer $NIMA_ACCESS_TOKEN"

OAuth endpoint error format

These endpoints answer with nima's error envelope, not the RFC 6749 {"error": "invalid_grant"} shape. An off-the-shelf OAuth client looking for that field will not find it. Read statusCode and error.

{
  "statusCode": 401,
  "error": "TOKEN_REPLAY",
  "message": "Authorization code has already been used",
  "timestamp": "2026-09-22T09:14:02.881Z",
  "path": "/oauth/token"
}

A 429 carries a Retry-After header with the whole seconds to wait: at most 30 for /oauth/register, /oauth/token and /oauth/revoke, and at most 60 for the other endpoints on this page. See Rate limits.

One 400 does not follow that pattern. A body that fails field validation before the handler runs, such as a missing grant_type or eleven redirect_uris, is answered by the framework rather than by nima:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Bad Request Exception",
  "timestamp": "2026-09-22T09:14:02.881Z",
  "path": "/oauth/register"
}

error is an English phrase there rather than a code, and the per-field messages are dropped on the way out, so it tells you the body was wrong and nothing else. Check the request against the parameters above. A 400 raised by the handler itself carries VALIDATION_ERROR and a message that names the problem.