API tokens

An API token lets a tool such as the Terraform provider call this API without a person signing in. A token belongs to one club and reaches only the areas of that club's configuration it was granted. Send it like a session token:

Authorization: Bearer chp_3f9c…

Secrets start with chp_ followed by 48 hexadecimal characters. Only a hash is stored: the secret is returned once, by createClubApiToken, and cannot be read again.

What a token can do

A token is for configuration only. It reaches the operations below, which are the ones the Terraform provider calls, and is refused everything else with API tokens cannot use this operation.: people, memberships, applications, reservations, billing, payment accounts, chats, the team, the platform, API tokens themselves, and public operations such as plans or signOut. An operation added to the API stays closed to tokens until it is added to this list.

Each operation belongs to one area. A token is granted read or write on each area it needs; an area left out is closed to it, and the operation answers This API token lacks the permission for this operation. with UNAUTHENTICATED.

clubApiTokenIdentity and platformApiTokenIdentity need no permission.

On the operations of its areas a token passes the checks a club administrator passes for its club, including modules the platform turned off for the club (refused to administrators too):

A token created with hidesPersonalData: true reads personal data pseudonymized, exactly like a staff account with the hidesPersonalData restriction: guest names in housekeeping and reservationFloorPlan read Member followed by a code, or Guest. Staff names are not member data and stay readable.

Permissions, hidesPersonalData, the name and the expiration date are set when the token is created and cannot be changed afterwards: create another token, then delete the first.

Activity recorded by a token names it API token <name>.

Identify the token

query TokenIdentity {
  clubApiTokenIdentity {
    id
    name
    permissions {
      area
      access
    }
    hidesPersonalData
    clubId
  }
}

Returns the token authenticating the request, or null for any other caller. Automation uses clubId as the clubId argument of every other operation.

Permissions

clubApiTokens, createClubApiToken, setClubApiTokenBlocked and deleteClubApiToken require a signed-in administrator of the club. Staff accounts are refused whatever their permissions, and so are API tokens.

List tokens

query ClubApiTokens($clubId: ID! = "51000000-0000-4000-8000-000000000051") {
  clubApiTokens(clubId: $clubId) {
    id
    name
    permissions {
      area
      access
    }
    hidesPersonalData
    hint
    createdBy
    createdAt
    lastUsedAt
    expiresAt
    blockedAt
    status
  }
}

Tokens are returned newest first, blocked and expired ones included. hint holds the last four characters of the secret, createdBy the name of the administrator who created the token (null once that account is deleted). lastUsedAt is refreshed at most once a minute. status is blocked while blockedAt is set, otherwise expired once expiresAt is reached, otherwise active.

Create a token

mutation CreateClubApiToken($input: CreateClubApiTokenInput!) {
  createClubApiToken(input: $input) {
    secret
    token {
      id
      name
      status
    }
  }
}

{
  "input": {
    "clubId": "51000000-0000-4000-8000-000000000051",
    "name": "Terraform, staging",
    "permissions": [
      { "area": "plans", "access": "write" },
      { "area": "settings", "access": "read" }
    ],
    "hidesPersonalData": true,
    "expiresAt": "2027-06-30T23:59:59+02:00"
  }
}

A club holds at most 20 tokens, blocked and expired ones included; beyond that the mutation answers Delete an API token before creating another one.

Block or unblock a token

mutation SetClubApiTokenBlocked($clubId: ID!, $id: ID!, $blocked: Boolean!) {
  setClubApiTokenBlocked(clubId: $clubId, id: $id, blocked: $blocked) {
    id
    status
    blockedAt
  }
}

Blocking is immediate and reversible. Blocking an already blocked token keeps its first blockedAt. Unblocking never revives an expired token. The mutation returns null when the club has no token with this id.

Delete a token

mutation DeleteClubApiToken($clubId: ID!, $id: ID!) {
  deleteClubApiToken(clubId: $clubId, id: $id)
}

Deletion is immediate and permanent: the token no longer authenticates and leaves the list. Returns false when the club has no token with this id.

Platform tokens

A platform token lets automation manage the clubs themselves, as the platform administration does. It belongs to no club and reads no club data. Its secret starts with chpp_ followed by 48 hexadecimal characters and is sent the same way.

platformApiTokenIdentity { id name access } returns the platform token authenticating the request, or null; clubApiTokenIdentity is null for a platform token and conversely.

Platform admins manage these tokens; club admins, space owners and API tokens are refused.

query PlatformApiTokens {
  platformApiTokens {
    id
    name
    access
    hint
    createdBy
    createdAt
    lastUsedAt
    expiresAt
    blockedAt
    status
  }
}
mutation CreatePlatformApiToken($name: String!, $access: ClubApiTokenAccess!, $expiresAt: String) {
  createPlatformApiToken(name: $name, access: $access, expiresAt: $expiresAt) {
    secret
    token {
      id
      name
    }
  }
}
mutation SetPlatformApiTokenBlocked($id: ID!, $blocked: Boolean!) {
  setPlatformApiTokenBlocked(id: $id, blocked: $blocked) {
    id
    status
    blockedAt
  }
}
mutation DeletePlatformApiToken($id: ID!) {
  deletePlatformApiToken(id: $id)
}

Names, expiration dates, blocking and deletion follow the rules of club tokens; a platform token keeps a single read or write access instead of per-area permissions. The platform holds at most 20 tokens, and creations, blockings, unblockings and deletions are recorded in the platform history.