Authentication

The API uses OAuth 2.0 with PKCE for authentication.

Note: Basic authentication is deprecated and will be removed in a future update. Please migrate to OAuth 2.0.

How it works

1. You create an OAuth application once to get a client_id
2. You redirect the user to the authorization endpoint where they log in
3. You receive an authorization code which you exchange for access and refresh tokens
4. You use the access token to make API requests

Tip: Most OAuth 2.0 client libraries handle this flow automatically. Point your library at the server metadata endpoint /.well-known/oauth-authorization-server for automatic configuration.

All endpoints below are relative to https://api.attendium.com.

Create your OAuth application

Create an OAuth application in Attendium to get your client_id, and your client_secret if it is a confidential application. You only need to do this once per application. See Create an OAuth application.

Redirect URIs must use https, or http with a loopback address (localhost, 127.0.0.1, or ::1) for local development. A public application may also use a private-use URI scheme in reverse-domain notation, such as com.example.app:/oauth/callback.

By creating an OAuth application — whether in Attendium or through Dynamic Client Registration — you accept the Developer terms in the version published at the time.

Authorize

Generate a PKCE code verifier and challenge:

1. Create a random string (43–128 characters, using A-Z, a-z, 0-9, -, ., _, ~) — this is your code_verifier
2. Compute the SHA-256 hash of the verifier and base64url-encode it — this is your code_challenge

Then redirect the user to:

GET /oauth2/authorize?response_type=code
  &client_id=your-client-id
  &redirect_uri=https://yourapp.example.com/callback
  &code_challenge=your-code-challenge
  &code_challenge_method=S256
  &state=random-state-value

The user logs in to Attendium and is redirected back to your redirect_uri with an authorization code and your state value.

Exchange the code for tokens

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=your-client-id
&redirect_uri=https://yourapp.example.com/callback
&code=the-authorization-code
&code_verifier=your-code-verifier

A confidential application must also authenticate itself, either with basic authentication (client_secret_basic) or by sending client_secret in the request body (client_secret_post):

POST /oauth2/token
Authorization: Basic base64(your-client-id:your-client-secret)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&redirect_uri=https://yourapp.example.com/callback
&code=the-authorization-code
&code_verifier=your-code-verifier

The response includes an access_token and a refresh_token.

Make API requests

Include the access token in the Authorization header:

curl -H "Authorization: Bearer your-access-token" \
     -H "Content-Type: application/json" \
     -d '{"query": "{ me { id } }"}' \
     https://api.attendium.com/graphql

Refresh the access token

The token response includes an expires_in field indicating how long the access token is valid. Use the refresh token to get a new access token before it expires:

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=your-client-id
&refresh_token=your-refresh-token

A confidential application authenticates this request the same way as the authorization code exchange.

Dynamic client registration

Applications that configure themselves from the server metadata — including AI assistants connecting over MCP, see Set up MCP — register themselves by sending a POST request to /oauth2/register. You do not need this if you create your OAuth application in Attendium.

POST /oauth2/register
Content-Type: application/json

{
  "redirect_uris": ["https://yourapp.example.com/callback"],
  "client_name": "My Application"
}

An application registered this way is not listed under OAuth applications, so its name, redirect URIs and client secret cannot be changed there.

Further reading

• OAuth 2.0 — oauth.net
• PKCE — RFC 7636
• Dynamic client registration — RFC 7591