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.

Links¶

Name	Method	Resource
delete	DELETE	API Token Resource
self	GET	API Token Resource
update	PUT	API Token Resource

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/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"
}