Skip to content

Authorization

The Gamma API uses a mix of OAuth 2.0 and Pre-shared keys (PSK) for authorization.

Authorization Flows

Gamma currently supports the Authorization Code Flow and Client authorization using API keys.

Authorization Code Flow

This OAuth 2.0 Authorization Code flow is used when accessing protected resources belonging to the end-user, such as when authenticating a user (verifying who they are) by fetching their user info.

This section describes the specifics of using the authorization code flow with Gamma. For more details about the flow itself, see this article about the Authorization Code flow by Auth0.

For an example of how to use the flow, see the Quickstart Guide.

// TODO: Actually document how the flow works

Getting an access token

These are the paths for the OAuth 2.0 endpoints. They are relative to https://auth.chalmers.it.

HTTP Method Path Name Description
GET /oauth2/authorize Authorization User is sent here when authorizing the client
POST /oauth2/token Token Authorization code is posted here to get an access token

After getting an access token it is provided in requests as part of the Authorization header:

Authorization: Bearer <ACCESS TOKEN>

Scopes

Client scopes are sent to Gamma in the authorization URL as the scope query parameter. Scopes allow a client to access personal information of users. Clients must use all scopes which they have, or else a mismatched scopes error will be presented to the user. All clients have the openid and profile scopes by default and the email scope if the client was created with the Include email scope option.

Scope Gives access to
openid OpenID information like user ID and JWT properties.
profile Profile information like CID and names.
email The user's email.

Super Group Restrictions

Official Gamma clients are able to restrict access to specified super groups. Users not in these super groups will see an error screen when trying to authorize. See Official Clients in the website reference for how to manage restrictions.

API Keys

Info

API keys are planned to be replaced by the Client Credentials flow in Gamma v31.

API keys are used in machine-to-machine authentication when accessing protected resources from the Gamma APIs. Using API keys is not a real authorization flow, it is just a shared secret which Gamma accepts.

Gamma has four types of API keys, corresponding to each API:

  • CLIENT
  • INFO
  • ALLOW_LIST
  • ACCOUNT_SCAFFOLD

Each type of API key can only access the API which matches its own type. These are also included in the table at the top of each API reference page. CLIENT API keys can be created by any Gamma user when creating a client and are linked to that client. Other types of API keys are standalone and can only be created by Gamma administrators.

All API keys have an ID and a token which are sent together in the Authorization header on each request to the Gamma API. The API key is sent in the following format:

Authorization: pre-shared <KEY ID>:<API TOKEN>

Last modified on: 2026-06-18 19:24:35

  1. cthit/Gamma issue #954 on GitHub, Support client credentials grant for api authentication — https://github.com/cthit/Gamma/issues/954 ↩