Client API¶

Get information about users who have authorized the client, hereafter referred to as a "user of the client".

Name	Value
API Key Type	`CLIENT`
Base URL	https://auth.chalmers.it/api/client/v1
API Controller	ClientApiV1Controller

Note

The email scope does not make e-mails visible in the Client API. Use the OpenID or Account Scaffold API instead.

Table of Contents

Client Authorities
Types
- User
- Group
- Group with Post
- Post
- Super Group
Endpoints Reference

Client Authorities¶

Client authorities are a way to designate certain super groups or users special "authorities" in the client without hardcoding ids or names. Client authorities are, for example, used by BookIT to give the "admin" authority to users who should be able to manage bookings and rules¹.

A client authority is simply a string label added to certain users. Using the Client API it is possible to get a list of client authorities a user has. The authority will be included in the list if:

The user is in a group which belongs to any of the super groups which have been added to the client authority.
The user is one of the users which have been added to the client authority.

See how to manage client authorities in the Creating client authorities section of the website documentation.

Types¶

These are the types used in the Client API.

User¶

Describes a user of the client.

id: UserId
cid: string
nick: string
firstName: string
lastName: string
acceptanceYear: int

Example

{
  "id": "2f63a363-af22-480d-be49-531c1831933c",
  "cid": "janed",
  "nick": "Dough",
  "firstName": "Jane",
  "lastName": "Doe",
  "acceptanceYear": 2025
}

Group¶

Describes a Gamma group.

id: GroupId
name: string
prettyName: string
superGroup: SuperGroup

Example

{
  "id": "7ec28eaa-7203-47fb-9c80-8b1678936be9",
  "name": "prit26",
  "prettyName": "P.R.I.T. 26",
  "superGroup": {
    "id": "32da51ec-2854-4bc2-b19a-30dad5dcc501",
    "name": "prit",
    "prettyName": "P.R.I.T.",
    "type": "committee",
    "svDescription": "PR och rustm\u00e4steri",
    "enDescription": "PR and premises maintenance"
  }
}

Group with Post¶

id: GroupId
name: string
prettyName: string
superGroup: SuperGroup
post: Post

Example

{
  "id": "3cf94646-2412-4896-bba9-5d2410ac0c62",
  "name": "prit25",
  "prettyName": "P.R.I.T. 25",
  "superGroup": {
    "id": "f06d3eb5-c718-4857-9fac-c457a3ab82a7",
    "name": "sprit",
    "prettyName": "S.P.R.I.T.",
    "type": "alumni",
    "svDescription": "",
    "enDescription": ""
  },
  "post": {
    "id": "0b960919-6dc0-4128-b772-c31840b7b8f7",
    "version": 30,
    "svName": "MaterialChef",
    "enName": "MaterialChef"
  }
}

Post¶

id: PostId
version: int
svName: string
enName: string

Example

{
  "id": "2a1a66a2-8e58-461c-96f1-9408a9c543f9",
  "version": 30,
  "svName": "Medlem",
  "enName": "Member"
}

Super Group¶

Describes a Gamma super group.

id: SuperGroupId
name: string
prettyName: string
type: "alumni" | "committee" | "functionaries" | "society"
svDescription: string
enDescription: string

Example

{
  "id": "dea3493e-66e4-44b2-a657-cb57a6840dab",
  "name": "digit",
  "prettyName": "digIT",
  "type": "committee",
  "svDescription": "Digitala system",
  "enDescription": "Digital systems"
}

Endpoints Reference¶

The Client API is currently hosted at https://auth.chalmers.it/api/client/v1 and all endpoints in this section are relative to this URL.

GET /users¶

Get all users of the client.

Return type: User list

Example¶

Click to show example request and response

Request¶

GET /users

Response¶

[
  {
    "id": "2f63a363-af22-480d-be49-531c1831933c",
    "cid": "janed",
    "nick": "Dough",
    "firstName": "Jane",
    "lastName": "Doe",
    "acceptanceYear": 2025
  },
  {
    "id": "9acb43d4-42f3-4f9d-9f37-bc156463e1a5",
    "cid": "smithj",
    "nick": "Smithed",
    "firstName": "John",
    "lastName": "Smith",
    "acceptanceYear": 2026
  }
]

GET /users/{id}¶

Get a user of the client.

Return type: User

Parameters¶

Name	Type	Data Type	Description
id	path	UserId	The user UUID

Errors¶

If the user has not authorized the client.

Example¶

Click to show example request and response

Request¶

GET /users/2f63a363-af22-480d-be49-531c1831933c

Response¶

{
  "id": "2f63a363-af22-480d-be49-531c1831933c",
  "cid": "janed",
  "nick": "Dough",
  "firstName": "Jane",
  "lastName": "Doe",
  "acceptanceYear": 2025
}

GET /groups¶

Get all Gamma groups.

Return type: Group list

Example¶

Click to show example request and response

Request¶

GET /groups

Response¶

[
  {
    "id": "3cf94646-2412-4896-bba9-5d2410ac0c62",
    "name": "prit25",
    "prettyName": "P.R.I.T. 25",
    "superGroup": {
      "id": "f06d3eb5-c718-4857-9fac-c457a3ab82a7",
      "name": "sprit",
      "prettyName": "S.P.R.I.T.",
      "type": "alumni",
      "svDescription": "",
      "enDescription": ""
    }
  },
  {
    "id": "7ec28eaa-7203-47fb-9c80-8b1678936be9",
    "name": "prit26",
    "prettyName": "P.R.I.T. 26",
    "superGroup": {
      "id": "32da51ec-2854-4bc2-b19a-30dad5dcc501",
      "name": "prit",
      "prettyName": "P.R.I.T.",
      "type": "committee",
      "svDescription": "PR och rustm\u00e4steri",
      "enDescription": "PR and premises maintenance"
    }
  },
  {
    "id": "64c623a0-31ce-4519-9fbf-67f207f88286",
    "name": "fikit25",
    "prettyName": "FikIT 25",
    "superGroup": {
      "id": "f5dd9c81-838b-49ec-bab4-a831331c4dc2",
      "name": "fikit",
      "prettyName": "FikIT",
      "type": "society",
      "svDescription": "",
      "enDescription": ""
    }
  },
  {
    "id": "59c01004-a961-499c-96ef-1a3785f9ddd8",
    "name": "samlag25",
    "prettyName": "SAMLAG 25",
    "superGroup": {
      "id": "2d75da98-c4a0-43af-9067-61320c891185",
      "name": "samlag",
      "prettyName": "Skol-Avslutnings-Musik-Ledar-Arbets-Gruppen",
      "type": "functionaries",
      "svDescription": "Skolavlutning",
      "enDescription": "End of year choir"
    }
  }
]

GET /groups/for/{id}¶

Get all groups which a user of the client is in.

Return type: Group with Post list

Parameters¶

Name	Type	Data Type	Description
id	path	UserId	The user UUID

Errors¶

If the user has not authorized the client.

Example¶

Click to show example request and response

Request¶

GET /groups/for/2f63a363-af22-480d-be49-531c1831933c

Response¶

[
  {
    "id": "3cf94646-2412-4896-bba9-5d2410ac0c62",
    "name": "prit25",
    "prettyName": "P.R.I.T. 25",
    "superGroup": {
      "id": "f06d3eb5-c718-4857-9fac-c457a3ab82a7",
      "name": "sprit",
      "prettyName": "S.P.R.I.T.",
      "type": "alumni",
      "svDescription": "",
      "enDescription": ""
    },
    "post": {
      "id": "0b960919-6dc0-4128-b772-c31840b7b8f7",
      "version": 30,
      "svName": "MaterialChef",
      "enName": "MaterialChef"
    }
  },
  {
    "id": "01b42763-eeb5-4989-8c8d-364b472f592c",
    "name": "hookit26",
    "prettyName": "HookIT 26",
    "superGroup": {
      "id": "8f87a4ac-869f-4a6a-a64e-815eb551d1da",
      "name": "hookit",
      "prettyName": "HookIT",
      "type": "society",
      "svDescription": "",
      "enDescription": ""
    },
    "post": {
      "id": "2a1a66a2-8e58-461c-96f1-9408a9c543f9",
      "version": 30,
      "svName": "Medlem",
      "enName": "Member"
    }
  }
]

GET /superGroups¶

Get all Gamma super groups.

Return type: Super group list

Example¶

Click to show example request and response

Request¶

GET /superGroups

Response¶

[
  {
    "id": "f06d3eb5-c718-4857-9fac-c457a3ab82a7",
    "name": "sprit",
    "prettyName": "S.P.R.I.T.",
    "type": "alumni",
    "svDescription": "",
    "enDescription": ""
  },
  {
    "id": "32da51ec-2854-4bc2-b19a-30dad5dcc501",
    "name": "prit",
    "prettyName": "P.R.I.T.",
    "type": "committee",
    "svDescription": "PR och rustm\u00e4steri",
    "enDescription": "PR and premises maintenance"
  },
  {
    "id": "f5dd9c81-838b-49ec-bab4-a831331c4dc2",
    "name": "fikit",
    "prettyName": "FikIT",
    "type": "society",
    "svDescription": "",
    "enDescription": ""
  },
  {
    "id": "2d75da98-c4a0-43af-9067-61320c891185",
    "name": "samlag",
    "prettyName": "Skol-Avslutnings-Musik-Ledar-Arbets-Gruppen",
    "type": "functionaries",
    "svDescription": "Skolavlutning",
    "enDescription": "End of year choir"
  }
]

Parameters¶

Name	Type	Data Type	Description
id	path	UserId	The user UUID

GET /authorities¶

Get the names of all client authorities on the client.

Return type: String list

Example¶

Click to show example request and response

Request¶

GET /authorities

Response¶

[
  "clientadmins",
  "specialuser"
]

GET /authorities/for/{id}¶

Get the names of the client authorities which the user belongs to.

Note

Unlike groups the user does not need to have authorized the client in order for the client to check their authorities.

Return type: String list

Parameters¶

Name	Type	Data Type	Description
id	path	UserId	The user UUID

Example¶

Click to show example request and response

Request¶

GET /authorities/2f63a363-af22-480d-be49-531c1831933c

Response¶

[
  "specialuser"
]

Last modified on: 2026-04-10 16:32:25

is_admin property in backend/src/index.ts. cthit/bookIT-node on GitHub — https://github.com/cthit/bookIT-node/blame/2378a279d047edffb0d1e967904e9fcf3824fa17/backend/src/index.ts#L46 ↩