Jump to >

This documentation covers the in-development release of Review Board. You can see the latest stable docs or all previous versions.

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_updatedISO 8601 Date/Time The date and time that the token was last updated.
noteString The note explaining the purpose of this token.
policyDictionary The access policies defined for this token.
time_addedISO 8601 Date/Time The date and time that the token was added.
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
112 - OAuth2 Missing Scope ErrorHTTP 403 - Forbidden Your OAuth2 token lacks the necessary scopes for this request.
113 - OAuth2 Access Denied ErrorHTTP 403 - Forbidden OAuth2 token access for this resource is prohibited.

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
112 - OAuth2 Missing Scope ErrorHTTP 403 - Forbidden Your OAuth2 token lacks the necessary scopes for this request.
113 - OAuth2 Access Denied ErrorHTTP 403 - Forbidden OAuth2 token access for this resource is prohibited.

HTTP PUT

Updates the information on an existing API token.

The note, policy, and extra data on the token may be updated. See Storing/Accessing Extra Data for more information.

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
112 - OAuth2 Missing Scope ErrorHTTP 403 - Forbidden Your OAuth2 token lacks the necessary scopes for this request.
113 - OAuth2 Access Denied ErrorHTTP 403 - Forbidden OAuth2 token access for this resource is prohibited.

Examples

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

$ curl http://reviews.example.com/apiadmin/1/ -H "Accept: application/json"
Last-Modified: Tue, 08 Jul 2014 10:58:04 GMT
ETag: 2b8252ad3361deb8d8760d48113ea5323c38dcbf
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"
}