Admin API for managing Registration Tokens #26

Closed
opened 2023-09-05 20:47:47 -05:00 by jordan · 1 comment
Owner

The administrator API should provide functions for managing registration tokens. This issue documents the endpoints and how they should be implemented.

GET /_telodendria/admin/tokens

Gets a list of all tokens present, and additional information.

Requires TokenRate LimitedPermissions
YesYesISSUE_TOKENS
Error ResponseDescription
200Token list was successfully retrieved.
403User does not have the ISSUE_TOKENS permission.

200 Response JSON Format:

FieldTypeDescription
tokenslist[TokenInfo]A list of tokens and other information.

TokenInfo JSON Format:

FieldTypeDescription
namestringThe token's name.
created_bylocalpartThe user who has created token.
created_ontimestampThe creation date of the token.
expires_ontimestampThe token's expiration date, or 0 if it does not expire.
usedintegerThe number of times the token was used.
usesintegerThe number of uses remaining for the token, or -1 if there are an unlimited number of uses remaining.

403 Response JSON Format:

FieldTypeDescription
errcodestringSet to ``M_FORBIDDEN''
errorstringHuman-readable explanation of the privilege issue.

200 Response Example:

{
  "tokens": [
    {
      "name": "forbob",
      "created_by": "alice",
      "created_on": 1234567890123,
      "expires_on": 2147483647000,
      "used": 1,
      "uses": 3
    }
  ]
}

403 Response JSON Format:

{
  "errcode": "M_FORBIDDEN",
  "error": "Forbidden access. Bad permissions or not authenticated."
}

GET /_telodendria/admin/tokens/[token]

Returns information about a specific registration token.

Requires TokenRate LimitedPermissions
YesYesISSUE_TOKENS
Error ResponseDescription
200Token information successfully retrieved.
403User does not have the ISSUE_TOKENS permission.
404The specified token does not exist.

200 Response JSON Format:

FieldTypeDescription
namestringThe token's name.
created_bylocalpartThe user who created the token.
created_ontimestampThe creation date of the token.
expires_ontimestampThe token's expiration date, if provided.
usedintegerThe number of times the token was used.
usesintegerThe number of remaining uses for the token, if set. Otherwise, there are unlimited uses remaining.

200 Response Example:

{
  "name": "forbob",
  "created_by": "alice",
  "created_on": 1234567890123,
  "used": 1,
  "uses": 3
}

POST /_telodendria/admin/tokens

Adds a registration token, and setup expiry date and max uses.

Requires TokenRate LimitedPermissions
YesYesISSUE_TOKENS

Request JSON Format:

FieldTypeDescriptionRequired
lifetimetimestampHow long this token should be good forNO
max_usesintegerThe maximum number of uses for this tokenNO
namestringA name for the token. If none is provided, then a name is randomly generated.NO

Request Example:

{
  "name": "OnlyClownsM7iAhUJD",
  "expires": 2147484637000,
  "max_uses": 5
}
Error ResponseDescription
200Token was successfully created.
403User does not have the ISSUE_TOKENS permission.

200 Response JSON Format:

FieldTypeDescription
namestringThe token's name.
created_bylocalpartThe user who created the token.
created_ontimestampThe creation date of the token.
expires_ontimestampThe token's expiration date, if set. If not set, the token never expires.
usedintegerThe number of times the token was used.
usesintegerThe number of uses remaining for the token, if set. If not set, the token has an unlimited number of uses.

200 Response Example:

{
  "name": "OnlyClownsM7iAhUJD",
  "created_by": "donald",
  "created_on": 1234567890123,
  "expires_on": 2147484637000,
  "used": 0,
  "uses": 5
}

403 Response JSON Format:

{
  "errcode": "M_FORBIDDEN",
  "error": "Forbidden access. Bad permissions or not authenticated."
}

DELETE /_telodendria/admin/tokens/[tokenname]

Requires TokenRate LimitedPermissions
YesYesISSUE_TOKENS

Description: Deletes an existing registration token.

Error ResponseDescription
204Token was successfully deleted.
403User does not have the ISSUE_TOKENS permission.

403 Response JSON Format:

{
  "errcode": "M_FORBIDDEN",
  "error": "Forbidden access. Bad permissions or not authenticated."
}
The administrator API should provide functions for managing registration tokens. This issue documents the endpoints and how they should be implemented. ### **GET** /_telodendria/admin/tokens Gets a list of *all* tokens present, and additional information. <table><tbody><tr><td>Requires Token</td><td>Rate Limited</td><td>Permissions</td></tr><tr><td>Yes</td><td>Yes</td><td>ISSUE_TOKENS</td></tr></tbody></table> <table><tbody><tr><td>Error Response</td><td>Description</td></tr><tr><td>200</td><td>Token list was successfully retrieved.</td></tr><tr><td>403</td><td>User does not have the ISSUE_TOKENS permission.</td></tr></tbody></table> 200 Response JSON Format: <table><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td>tokens</td><td>list[TokenInfo]</td><td>A list of tokens and other information.</td></tr></tbody></table> `TokenInfo` JSON Format: <table><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td>name</td><td>string</td><td>The token's name.</td></tr><tr><td>created_by</td><td>localpart</td><td>The user who has created token.</td></tr><tr><td>created_on</td><td>timestamp</td><td>The creation date of the token.</td></tr><tr><td>expires_on</td><td>timestamp</td><td>The token's expiration date, or 0 if it does not expire.</td></tr><tr><td>used</td><td>integer</td><td>The number of times the token was used.</td></tr><tr><td>uses</td><td>integer</td><td>The number of uses remaining for the token, or -1 if there are an unlimited number of uses remaining.</td></tr></tbody></table> 403 Response JSON Format: <table><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td>errcode</td><td>string</td><td>Set to ``M_FORBIDDEN''</td></tr><tr><td>error</td><td>string</td><td>Human-readable explanation of the privilege issue.</td></tr></tbody></table> 200 Response Example: ```json { "tokens": [ { "name": "forbob", "created_by": "alice", "created_on": 1234567890123, "expires_on": 2147483647000, "used": 1, "uses": 3 } ] } ``` 403 Response JSON Format: ```json { "errcode": "M_FORBIDDEN", "error": "Forbidden access. Bad permissions or not authenticated." } ``` ### **GET** /_telodendria/admin/tokens/\[token\] Returns information about a specific registration token. <table><tbody><tr><td>Requires Token</td><td>Rate Limited</td><td>Permissions</td></tr><tr><td>Yes</td><td>Yes</td><td>ISSUE_TOKENS</td></tr></tbody></table> <table><tbody><tr><td>Error Response</td><td>Description</td></tr><tr><td>200</td><td>Token information successfully retrieved.</td></tr><tr><td>403</td><td>User does not have the ISSUE_TOKENS permission.</td></tr><tr><td>404</td><td>The specified token does not exist.</td></tr></tbody></table> 200 Response JSON Format: <table><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td>name</td><td>string</td><td>The token's name.</td></tr><tr><td>created_by</td><td>localpart</td><td>The user who created the token.</td></tr><tr><td>created_on</td><td>timestamp</td><td>The creation date of the token.</td></tr><tr><td>expires_on</td><td>timestamp</td><td>The token's expiration date, if provided.</td></tr><tr><td>used</td><td>integer</td><td>The number of times the token was used.</td></tr><tr><td>uses</td><td>integer</td><td>The number of remaining uses for the token, if set. Otherwise, there are unlimited uses remaining.</td></tr></tbody></table> 200 Response Example: ```json { "name": "forbob", "created_by": "alice", "created_on": 1234567890123, "used": 1, "uses": 3 } ``` ### **POST** /_telodendria/admin/tokens Adds a registration token, and setup expiry date and max uses. <table><tbody><tr><td>Requires Token</td><td>Rate Limited</td><td>Permissions</td></tr><tr><td>Yes</td><td>Yes</td><td>ISSUE_TOKENS</td></tr></tbody></table> Request JSON Format: <table><tbody><tr><td>Field</td><td>Type</td><td>Description</td><td>Required</td></tr><tr><td>lifetime</td><td>timestamp</td><td>How long this token should be good for</td><td>NO</td></tr><tr><td>max_uses</td><td>integer</td><td>The maximum number of uses for this token</td><td>NO</td></tr><tr><td>name</td><td>string</td><td>A name for the token. If none is provided, then a name is randomly generated.</td><td>NO</td></tr></tbody></table> Request Example: ```json { "name": "OnlyClownsM7iAhUJD", "expires": 2147484637000, "max_uses": 5 } ``` <table><tbody><tr><td>Error Response</td><td>Description</td></tr><tr><td>200</td><td>Token was successfully created.</td></tr><tr><td>403</td><td>User does not have the ISSUE_TOKENS permission.</td></tr></tbody></table> 200 Response JSON Format: <table><tbody><tr><td>Field</td><td>Type</td><td>Description</td></tr><tr><td>name</td><td>string</td><td>The token's name.</td></tr><tr><td>created_by</td><td>localpart</td><td>The user who created the token.</td></tr><tr><td>created_on</td><td>timestamp</td><td>The creation date of the token.</td></tr><tr><td>expires_on</td><td>timestamp</td><td>The token's expiration date, if set. If not set, the token never expires.</td></tr><tr><td>used</td><td>integer</td><td>The number of times the token was used.</td></tr><tr><td>uses</td><td>integer</td><td>The number of uses remaining for the token, if set. If not set, the token has an unlimited number of uses.</td></tr></tbody></table> 200 Response Example: ```json { "name": "OnlyClownsM7iAhUJD", "created_by": "donald", "created_on": 1234567890123, "expires_on": 2147484637000, "used": 0, "uses": 5 } ``` 403 Response JSON Format: ```json { "errcode": "M_FORBIDDEN", "error": "Forbidden access. Bad permissions or not authenticated." } ``` ### **DELETE** /_telodendria/admin/tokens/\[tokenname\] <table><tbody><tr><td>Requires Token</td><td>Rate Limited</td><td>Permissions</td></tr><tr><td>Yes</td><td>Yes</td><td>ISSUE_TOKENS</td></tr></tbody></table> _Description:_ Deletes an existing registration token. <table><tbody><tr><td>Error Response</td><td>Description</td></tr><tr><td>204</td><td>Token was successfully deleted.</td></tr><tr><td>403</td><td>User does not have the ISSUE_TOKENS permission.</td></tr></tbody></table> 403 Response JSON Format: ```json { "errcode": "M_FORBIDDEN", "error": "Forbidden access. Bad permissions or not authenticated." } ```
jordan added the
enhancement
label 2023-09-05 20:47:47 -05:00
jordan added this to the Telodendria v1.7.0-alpha4 project 2023-09-05 20:47:48 -05:00
Author
Owner

And here's the checklist that we can update as we implement these:

  • GET /_telodendria/admin/tokens
  • GET /_telodendria/admin/tokens/[token]
  • POST /_telodendria/admin/tokens
  • DELETE /_telodendria/admin/tokens/[token]
And here's the checklist that we can update as we implement these: - [ ] **GET** /_telodendria/admin/tokens - [ ] **GET** /_telodendria/admin/tokens/[token] - [ ] **POST** /_telodendria/admin/tokens - [ ] **DELETE** /_telodendria/admin/tokens/[token]
Sign in to join this conversation.
No Milestone
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: Telodendria/Telodendria#26
No description provided.