Developer Tokens¶
Introduction¶
The Tokens API allows management of developer tokens.
Most of the developer APIs require a macaroon authenticated request to be able to operate with them. These set of endpoints provide ways to:
Get a root macaroon to be discharged by the Candid authentication service
Return basic user details for the authenticating user
The Tokens API is exposed at the following base URLs:
Staging: https://dashboard.staging.snapcraft.io/api/v2/tokens
Production: https://dashboard.snapcraft.io/api/v2/tokens
Response Format¶
JSON will be returned in all responses from the API, including error responses, please refer to the following section for details about the format.
Obtain a bakery V2 macaroon to be discharged by Candid.¶
Introduced in version 26
- POST /api/v2/tokens¶
Obtain a root macaroon to be discharged with identity information.
Return a bakery v2 macaroon to be discharged by Candid.
- status 200
success
- status 400
error
Changelog¶
Version 26: New API endpoints for Developer Tokens management.
Request JSON Schema¶
{
"additionalProperties": false,
"properties": {
"channels": {
"description": "A list of channels to restrict the macaroon to, allows wildcards in the fnmatch format (https://docs.python.org/3/library/fnmatch.html)",
"items": {
"description": "Valid channel name.",
"type": "string"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
},
"description": {
"description": "A description to help identify the macaroon",
"type": "string"
},
"expires": {
"description": "A timestamp (string formatted per ISO8601) after which the macaroon should not be valid. Only UTC values are allowed.",
"format": "date-time",
"type": "string"
},
"packages": {
"description": "A list of packages to restrict the macaroon to. Those can be defined in two ways: 1- by name: each item in the list should be a json dict like `{\"name\": \"the-name\"}`, or 2- by snap_id: each item in the list should be a json dict like `{\"snap_id\": \"some-snap-id-1234\"}`.",
"items": {
"anyOf": [
{
"required": [
"snap_id"
]
},
{
"required": [
"name"
]
}
],
"description": "Package identifier: a dict with at least name or snap_id keys.",
"properties": {
"name": {
"type": "string"
},
"snap_id": {
"type": "string"
}
},
"type": "object"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
},
"permissions": {
"description": "A list of permissions to restrict the macaroon to",
"items": {
"description": "A valid token permission.",
"enum": [
"edit_account",
"modify_account_key",
"package_access",
"package_manage",
"package_metrics",
"package_purchase",
"package_push",
"package_register",
"package_release",
"package_update",
"package_upload",
"package_upload_request",
"store_admin",
"store_review"
],
"type": "string"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
},
"store_ids": {
"description": "A list of store IDs to restrict the macaroon to",
"items": {
"description": "A store ID.",
"type": "string"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
}
},
"type": "object"
}
Response JSON Schema¶
{
"additionalProperties": false,
"properties": {
"macaroon": {
"description": "The bakery v2 macaroon to be discharged by Candid",
"type": "string"
}
},
"required": [
"macaroon"
],
"type": "object"
}
Obtain a bakery V2 macaroon for store authentication.¶
Introduced in version 30
- POST /api/v2/tokens/exchange¶
Return exchanged authentication macaroon from root and Candid discharge.
- status 200
success
- status 400
error
- status 401
unauthorized
Changelog¶
Version 30: New API endpoint for Developer Tokens exchange.
Request JSON Schema¶
{
"additionalProperties": false,
"type": "object"
}
Response JSON Schema¶
{
"additionalProperties": false,
"properties": {
"macaroon": {
"description": "The bakery v2 macaroon used for authentication",
"type": "string"
}
},
"required": [
"macaroon"
],
"type": "object"
}
List existing v2 bakery macaroons.¶
Introduced in version 31
- GET /api/v2/tokens¶
Return existing valid macaroons.
Passing ?include-inactive=true will also include revoked/expired macaroons.
- status 200
success
- status 400
error
- status 401
unauthorized
Changelog¶
Version 31: New API endpoint for Developer Tokens listing.
Response JSON Schema¶
{
"additionalProperties": false,
"properties": {
"macaroons": {
"items": {
"properties": {
"description": {
"type": [
"string",
"null"
]
},
"revoked-at": {
"type": [
"string",
"null"
]
},
"revoked-by": {
"type": [
"string",
"null"
]
},
"session-id": {
"type": "string"
},
"valid-since": {
"format": "date-time",
"type": "string"
},
"valid-until": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"required": [
"macaroons"
],
"type": "object"
}
Revoke specified v2 bakery macaroons.¶
Introduced in version 32
- POST /api/v2/tokens/revoke¶
Revoke specified macaroons.
Return the information of the revoked macaroons.
- status 200
success
- status 400
error
- status 401
unauthorized
Changelog¶
Version 32: New API endpoint for revoking Developer Tokens.
Request JSON Schema¶
{
"additionalProperties": false,
"properties": {
"session-id": {
"type": "string"
}
},
"required": [
"session-id"
],
"type": "object"
}
Response JSON Schema¶
{
"additionalProperties": false,
"properties": {
"macaroons": {
"items": {
"properties": {
"description": {
"type": [
"string",
"null"
]
},
"revoked-at": {
"type": [
"string",
"null"
]
},
"revoked-by": {
"type": [
"string",
"null"
]
},
"session-id": {
"type": "string"
},
"valid-since": {
"format": "date-time",
"type": "string"
},
"valid-until": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"required": [
"macaroons"
],
"type": "object"
}
Obtain user and token information from the authenticated request.¶
Introduced in version 27
- GET /api/v2/tokens/whoami¶
Get user account and token information from the authenticated request.
Return account information plus the attenuations bound to the token used to authenticate this request.
- status 200
success
- status 400
error
Changelog¶
Version 27: New API endpoints for obtaining user information.
Response JSON Schema¶
{
"additionalProperties": false,
"properties": {
"account": {
"additionalProperties": false,
"properties": {
"email": {
"description": "The primary email for the user",
"type": "string"
},
"id": {
"description": "The store account ID for the user",
"type": "string"
},
"name": {
"description": "The display name for the user",
"type": "string"
},
"username": {
"description": "The store username for the user",
"type": "string"
}
},
"required": [
"email",
"id",
"name",
"username"
],
"type": "object"
},
"channels": {
"oneOf": [
{
"description": "A list of channels to restrict the macaroon to, allows wildcards in the fnmatch format (https://docs.python.org/3/library/fnmatch.html)",
"items": {
"description": "Valid channel name.",
"type": "string"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
},
{
"type": "null"
}
]
},
"errors": {
"items": {
"properties": {
"code": {
"type": "string"
},
"extra": {
"additionalProperties": true,
"type": "object"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message",
"extra"
],
"type": "object"
},
"type": "array"
},
"expires": {
"oneOf": [
{
"description": "A timestamp (string formatted per ISO8601) after which the macaroon should not be valid. Only UTC values are allowed.",
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"packages": {
"oneOf": [
{
"description": "A list of snap_ids to restrict the macaroon to.",
"items": {
"description": "Package identifier (snap_id).",
"type": "string"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
},
{
"type": "null"
}
]
},
"permissions": {
"oneOf": [
{
"description": "A list of permissions to restrict the macaroon to",
"items": {
"description": "A valid token permission.",
"enum": [
"edit_account",
"modify_account_key",
"package_access",
"package_manage",
"package_metrics",
"package_purchase",
"package_push",
"package_register",
"package_release",
"package_update",
"package_upload",
"package_upload_request",
"store_admin",
"store_review"
],
"type": "string"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
},
{
"type": "null"
}
]
},
"store_ids": {
"oneOf": [
{
"description": "A list of store IDs to restrict the macaroon to",
"items": {
"description": "A store ID.",
"type": "string"
},
"minItems": 1,
"type": "array",
"uniqueItems": true
},
{
"type": "null"
}
]
}
},
"required": [
"account",
"channels",
"packages",
"permissions"
],
"type": "object"
}