Jump to >

API Token Resource

Added in 2.5

Manages the tokens used to access the API.

This resource allows callers to retrieve their list of tokens, register new tokens, delete old ones, and update information on existing tokens.

Details

Name api_token
URI /api/users/{username}/api-tokens/{api_token_id}/
Token Policy ID api_token
HTTP Methods
  • DELETE - Delete the API token, invalidating all clients using it.
  • GET - Retrieves information on a particular API token.
  • PUT - Updates the information on an existing API token.
Parent Resource API Token List Resource
Child Resources None
Anonymous Access Yes, if anonymous site access is enabled

Fields

extra_dataDictionary Extra data as part of the token. This can be set by the API or extensions.
idString The numeric ID of the token entry.
last_updatedString The date and time that the token was last updated (in YYYY-MM-DD HH:MM:SS format).
noteString The note explaining the purpose of this token.
policyDictionary The access policies defined for this token.
time_addedString The date and time that the token was added (in YYYY-MM-DD HH:MM:SS format).
tokenString The token value.

HTTP DELETE

Delete the API token, invalidating all clients using it.

The API token will be removed from the user’s account, and will no longer be usable for authentication.

After deletion, this will return a HTTP 204 No Content.

Errors

100 - Does Not ExistHTTP 404 - Not Found Object does not exist
101 - Permission DeniedHTTP 403 - Forbidden You don’t have permission for this
103 - Not Logged InHTTP 401 - Unauthorized You are not logged in

HTTP GET

Retrieves information on a particular API token.

This can only be accessed by the owner of the tokens, or superusers.

Errors

100 - Does Not ExistHTTP 404 - Not Found Object does not exist
101 - Permission DeniedHTTP 403 - Forbidden You don’t have permission for this
103 - Not Logged InHTTP 401 - Unauthorized You are not logged in

HTTP PUT

Updates the information on an existing API token.

The note, policy, and extra data on the token may be updated.

Request Parameters

noteString The note explaining the purpose of this token.
policyString The token access policy, encoded as a JSON string.

Errors

100 - Does Not ExistHTTP 404 - Not Found Object does not exist
101 - Permission DeniedHTTP 403 - Forbidden You don’t have permission for this
103 - Not Logged InHTTP 401 - Unauthorized You are not logged in
105 - Invalid Form DataHTTP 400 - Bad Request One or more fields had errors

Examples

application/vnd.reviewboard.org.api-token+json

$ curl http://reviews.example.com/api/users/admin/api-tokens/1/ -H "Accept: application/json"
Last-Modified: Tue, 08 Jul 2014 10:58:04 GMT
ETag: 7af71c4fc16e40a627ccb20eddcc03d7c9e021bc
Content-Type: application/vnd.reviewboard.org.api-token+json
X-Content-Type-Options: nosniff
Vary: Accept, Cookie
{
  "api_token": {
    "extra_data": {}, 
    "id": 1, 
    "last_updated": "2014-07-08T10:58:04Z", 
    "links": {
      "delete": {
        "href": "http://reviews.example.com/api/users/admin/api-tokens/1/", 
        "method": "DELETE"
      }, 
      "self": {
        "href": "http://reviews.example.com/api/users/admin/api-tokens/1/", 
        "method": "GET"
      }, 
      "update": {
        "href": "http://reviews.example.com/api/users/admin/api-tokens/1/", 
        "method": "PUT"
      }
    }, 
    "note": "This is my token for local testing.", 
    "policy": {
      "perms": "rw"
    }, 
    "time_added": "2014-07-08T10:58:04Z", 
    "token": "709b0f04ccbd22dc2b16af8c286bcba75f31eb6d"
  }, 
  "stat": "ok"
}