Grants

A grant lets one user (the grantor) open their stats to a specific API key held by someone else. The key owner can then read the grantor's stats through this API the same way they read their own. Grants are granted and revoked from the account page or the endpoints below, and they die automatically when the key they target is revoked.

GET /api/v1/grants Account

Lists the users who granted the calling key access to their data. The key owner's own user is never listed; their stats are always readable via /me.

Auth: Authorization: Bearer <key>

Example response

{
  "key_id": "key_9f3a",
  "grants": [
    {
      "slack_id": "U0123ABCD",
      "merged_name": "Orpheus",
      "created_at": 1736092800
    }
  ]
}
GET /api/v1/grants/{slack_id} Account

Returns the UserStats of a user who granted the calling key access. Identical shape to GET /api/v1/users/{slack_id}.

Path parameters

  • slack_id - Slack user id of the grantor.

Auth: Authorization: Bearer <key>

Responses

  • 200 - the grantor's UserStats.
  • 401 - missing or invalid API key.
  • 403 - this key holds no grant for that user.
POST /api/v1/grants Account

Grants the signed-in user's stats to the API key with the given public id (key_...), as shown on the owner's account page. Grants are idempotent: granting the same key twice just refreshes the timestamp.

Auth: signed-in session cookie.

CSRF: include the token from the st_csrf cookie in an X-CSRF-Token header.

Request body

{
  "key_id": "key_9f3a"
}

Responses

  • 201 - the grant was created.
  • 401 - not signed in.
  • 403 - missing or invalid CSRF token.
  • 404 - no such API key.

Example

curl -b session.cookie -H "Content-Type: application/json" \
     -H "X-CSRF-Token: <st_csrf from the account page>" \
     -d '{ "key_id": "key_9f3a" }' \
     https://shiptalkers.kirze.de/api/v1/grants
DELETE /api/v1/grants/{key_id} Account

Revokes the signed-in user's grant to the given key. The key immediately loses access to this user's stats. Grants also die on their own when the target key is revoked.

Path parameters

  • key_id - public id of the key to revoke access from.

Auth: signed-in session cookie.

CSRF: include the token from the st_csrf cookie in an X-CSRF-Token header.

Responses

  • 204 - revoked.
  • 401 - not signed in.
  • 403 - missing or invalid CSRF token.
  • 404 - no such grant for this user.