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

Fields¶

deprecatedBoolean	Whether the token is deprecated. This is true if the token was generated by a deprecated token generator. Added in 5.0.1
expiredBoolean	Whether the token is expired. Added in 5.0
expires Nullable ISO 8601 Date/Time	An optional field for the date and time that the token will expire. The token will be invalid and unusable for authentication after this point. Added in 5.0
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.
invalid_date ISO 8601 Date/Time	The date and time at which the token became invalid. Added in 5.0
invalid_reasonString	A message explaining why the token is no longer valid. Added in 5.0
last_updated ISO 8601 Date/Time	The date and time that the token was last updated.
last_used ISO 8601 Date/Time	The date and time that the token was last used for authentication. Added in 5.0
noteString	The note explaining the purpose of this token.
policyDictionary	The access policies defined for this token.
time_added ISO 8601 Date/Time	The date and time that the token was added.
tokenString	The token value.
token_generator_idString	The ID of the token generator that generated the token. Added in 5.0
validBoolean	Whether the token is currently valid. Added in 5.0

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.

This can also be used to invalidate a token by setting valid to false and including an invalid reason.

Request Parameters¶

expires Nullable ISO 8601 Date/Time	The date and time that the token will expire.This must be a valid date/time format. Added in 5.0
invalid_reasonString	A message indicating why the token is no longer valid. Added in 5.0
noteString	The note explaining the purpose of this token.
policyString	The token access policy, encoded as a JSON string.
validBoolean	Whether the token is valid. This can only be used to invalidate tokens by setting this to `false`. Setting this to `true` is not allowed and will cause an invalid form data error. Added in 5.0

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 https://reviews.example.com/api/users/admin/api-tokens/1/ -H "Accept: application/json"

HTTP 200 OK
Content-Length: 751
Content-Type: application/vnd.reviewboard.org.api-token+json
ETag: e9d4219124005d1f4ce3d8349a1810e819740a2b
Last-Modified: Tue, 08 Jul 2014 10:58:04 GMT
Vary: Accept, Cookie
X-Content-Type-Options: nosniff

{
  "api_token": {
    "deprecated": false,
    "expired": false,
    "expires": null,
    "extra_data": {},
    "id": 1,
    "invalid_date": null,
    "invalid_reason": "",
    "last_updated": "2014-07-08T10:58:04.652000+00:00",
    "last_used": null,
    "links": {
      "delete": {
        "href": "https://reviews.example.com/api/users/admin/api-tokens/1/",
        "method": "DELETE"
      },
      "self": {
        "href": "https://reviews.example.com/api/users/admin/api-tokens/1/",
        "method": "GET"
      },
      "update": {
        "href": "https://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:04.652000+00:00",
    "token": "709b0f04ccbd22dc2b16af8c286bcba75f31eb6d",
    "token_generator_id": "",
    "valid": true
  },
  "stat": "ok"
}