Home | /api | v1 | auth

/api/v1/auth/self

The authentication context of the request: what the server concluded from the credentials it was given.

GET

Returns the auth context. Never fails: with no credentials, or with credentials that cannot be resolved, it returns the guest context.

The response is one of four objects, told apart by "type".

Guest

No credentials, or credentials that could not be resolved.

GET /api/v1/auth/self

{
  "type": "Guest",
  "scope": "Default"
}

User

A browser session (the sid cookie) or HTTP Basic credentials.

GET /api/v1/auth/self
Cookie: sid=b8be19ef-2d61-44de-b7d2-9c34ccb8a763

{
  "type": "User",
  "scope": "Default",
  "user": {
    "type": "User",
    "id": "9f310484-963b-446b-af69-797feec6813f",
    "display_name": {
      "current": {
        "value": "Demurgos"
      }
    }
  },
  "is_administrator": true
}

AccessToken

An OAuth access token: an application acting on behalf of a user.

GET /api/v1/auth/self
Authorization: Bearer 5f6613eb-880f-4b01-8e71-96b644e4584f

{
  "type": "AccessToken",
  "scope": "Default",
  "client": {
    "type": "OauthClient",
    "id": "d19e61a3-83d3-410f-84ec-49aaab841559",
    "key": "eternalfest@clients",
    "display_name": "Eternalfest"
  },
  "user": {
    "type": "User",
    "id": "9f310484-963b-446b-af69-797feec6813f",
    "display_name": {
      "current": {
        "value": "Demurgos"
      }
    }
  },
  "scopes": {
    "base": true,
    "forum_read": false,
    "forum_write": false,
    "forum_moderate": false
  }
}

scopes is what the token was granted, and it is narrower than what the user themself may do: a token holding only base may not write on the forum even if its user is a moderator. It is distinct from scope, which is the single-valued scope of the context and is always "Default" today.

There is no is_administrator on this variant, on purpose: an administrator who signs into a game does not carry administrator powers into it.

Tokens issued before the scopes field existed read back as base alone.

OauthClient

An OAuth client authenticating as itself, with no user behind it (HTTP Basic with the client key and secret). This is what the OpenTelemetry collectors expect.

{
  "type": "OauthClient",
  "scope": "Default",
  "client": {
    "type": "OauthClient",
    "id": "d19e61a3-83d3-410f-84ec-49aaab841559",
    "key": "eternalfest@clients",
    "display_name": "Eternalfest"
  }
}

PUT

Signs in with Eternaltwin credentials and opens a session.

Query parameters

Body

The hexadecimal encoding of the password is not an accident: the field is a byte buffer, so "aaaaaaaaaa" travels as "61616161616161616161".

Signing in asks for a captcha only once the calling address has got the password wrong several times over, so most requests carry no cap-token. When one is required, the response is 401 with the message "captcha is required"; solve a challenge from /api/v1/captcha with the scope login and retry.

Response

200 with the user, plus a Set-Cookie header carrying the new session:

PUT /api/v1/auth/self?method=Etwin
Content-Type: application/json

{"login": "alice", "password": "61616161616161616161"}

HTTP/1.1 200 OK
Set-Cookie: sid=1a6e0f24-9de4-4d04-8b48-6c1d8f26f3bb; HttpOnly; Path=/

{
  "type": "User",
  "id": "28dbb0bf-0fdc-40fe-ae5a-dde193f9fea8",
  "created_at": "2021-01-15T14:17:14.015Z",
  "deleted_at": null,
  "display_name": {
    "current": {
      "value": "Alice"
    }
  },
  "is_administrator": true,
  "links": {
    "dinoparc_com": {"current": null, "old": []},
    "en_dinoparc_com": {"current": null, "old": []},
    "hammerfest_es": {"current": null, "old": []},
    "hammerfest_fr": {"current": null, "old": []},
    "hfest_net": {"current": null, "old": []},
    "sp_dinoparc_com": {"current": null, "old": []},
    "twinoid": {"current": null, "old": []}
  }
}

Errors

DELETE

Signs out. Clears the sid cookie and returns the guest context. Needs no body and no credentials.

DELETE /api/v1/auth/self

HTTP/1.1 200 OK
Set-Cookie: sid=; HttpOnly; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT

{
  "type": "Guest",
  "scope": "Default"
}