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