Authentication

Authentication is required to access protected resources in the Gatsby API. The API supports two ways to authenticate: API tokens, the recommended approach, and access tokens obtained from an email and password login, which is still supported but no longer recommended.

We recommend authenticating with an API token. The email and password login flow described under Access tokens continues to work, but it is no longer the recommended approach for new integrations.

API tokens

An API token is a long-lived credential that is tied to a single organization. Because the organization is bound to the token itself, you only need to send a single header with your requests — the organizationSlug header is not required when authenticating with an API token.

Enabling API tokens

API tokens must be enabled for your organization before you can create one. To request access, email help@gatsby.events and ask to have API tokens enabled for your organization.

Creating an API token

Once API tokens are enabled, a Super Admin or Admin can create one from the Gatsby dashboard under Team Settings → Linked Services → API Keys. Copy the token when it is first shown — for security, it is only displayed once. API tokens begin with the gat_ prefix.

Making authenticated requests

Include your API token in the x-api-key header on every request:

x-api-key: {your-api-token}

API token example

GET
/person
curl https://rest.gatsby.events/person \
  -H "x-api-key: {your-api-token}"

Treat your API token like a password. Keep it secret, never commit it to source control, and rotate it if it is ever exposed. A token can be revoked at any time from Team Settings → API Keys.

Access tokens (legacy)

This email and password flow still works, but we recommend authenticating with an API token instead.

To authenticate with an access token you need to:

  1. Log in with your email and password to obtain an access token
  2. Include this token in all subsequent requests in the Authorization header
  3. Include your organization slug in the organizationSlug header

Unlike an API token, an access token is not tied to a single organization, so both the access token and organization slug are required in the headers of every request (except for login):

Authorization: Bearer {accessToken}
organizationSlug: {organizationSlug}

Access token example

import axios from 'axios';

// Step 1: Login to get access token
const loginResponse = await axios.post('https://rest.gatsby.events/login', {
  email: 'your-email@example.com',
  password: 'your-password'
});

const { accessToken, organizationSlugs } = loginResponse.data;
const organizationSlug = organizationSlugs[0]; // Choose an organization

// Step 2: Setup headers for future requests
axios.defaults.headers.common['Authorization'] = `Bearer ${accessToken}`;
axios.defaults.headers.common['organizationSlug'] = organizationSlug;

// Step 3: Make authenticated requests
const response = await axios.get('https://rest.gatsby.events/person');

Error Handling

When an authentication error occurs, the API will return a 401 Unauthorized status code along with an error message in the response body. Always check response status codes and handle authentication errors appropriately in your application.

For detailed information about authentication endpoints, please refer to the Auth section.

Was this page helpful?