Skip to content

Get a token

There are two kinds of credential. Interactive clients use OAuth sign-in. Scripts and CI use a personal access token.

MCP clients such as Claude and ChatGPT, and your own application, sign in with OAuth 2.1 authorization code and PKCE against the emely authorization server. An MCP client does this for you when you connect.

The requested scope decides what the token may do:

  • openid graphql:role:api_user reads and writes your own data, such as your society memberships.
  • openid graphql:role:api_operator is for operators and maintains the shared society catalogue.

See Authentication for the flow, the issuer and the token details.

For a script or a job, create a personal access token in the app under Account settings, API tokens. Choose an expiry of up to 365 days. The token is shown once at creation; copy it then.

Send it as a bearer token:

Terminal window
curl -H "Authorization: Bearer <token>" https://api.emely.io/v1/me/society-memberships

A personal access token works on the /v1/me/ routes and the shared catalogue reads. The operator routes refuse it with 403. Revoke a token in the same tab.

  • Treat a token like a password. It acts as you.
  • The API never returns a session for a personal access token; the exchange happens server-side.
  • Revoke a token if it leaks.
  • A revoked token can keep working for at most about 14 minutes per API instance, the remaining life of the session the API caches for it.
  • If a token leaks, revoke it and then use Sign out everywhere in Account settings: a token can also open a normal session, and revoking the token does not end sessions already opened with it.
  • A caller can make at most 5 new token exchanges per 5 minutes. Cached sessions do not count. Past the limit the API answers 429 with a Retry-After header.
  • A 503 with a Retry-After header means the sign-in service is busy; retry later.