Telodendria/Telodendria
Telodendria
/
Telodendria
3
6
Fork 8
Code Issues 8 Pull Requests 1 Actions Projects 3 Releases 4 Wiki Activity

Admin API for managing Registration Tokens #26

New Issue
Closed
opened 2023-09-05 21:47:47 -04:00 by jordan · 1 comment
jordan commented 2023-09-05 21:47:47 -04:00
Owner
Copy Link

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 21:47:47 -04:00
jordan added this to the Telodendria v1.7.0-alpha4 project 2023-09-05 21:47:48 -04:00
jordan commented 2023-09-05 21:49:12 -04:00
Author
Owner
Copy Link

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 Branch/Tag Specified
Branches Tags
master
Telodendria-0_3_0
Telodendria-0_2_1
Telodendria-0_2_0
Telodendria-0_1_0
Labels
Clear labels   
bug

Something is not working

  
duplicate

This issue or pull request already exists

  
enhancement

New feature

  
help wanted

Need some help

  
invalid

Something is wrong

  
question

More information is needed

  
wontfix

This won't be fixed

No Label
bug
duplicate
enhancement
help wanted
invalid
question
wontfix
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Telodendria v1.7.0-alpha4
Assignees
Clear assignees
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.
Delete Branch "%!s(<nil>)"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?