Workspace: keys

Agent keys: the caller’s own, or every owner’s for an admin. Never the keys themselves

GET /v1/workspace/keys · operation listApiKeys

Requires the batondeck:workspace:read permission (action apikey:read).

Responses

Status	Meaning
200	Agent keys: the caller’s own, or every owner’s for an admin. Never the keys themselves
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

200 response schema

{
  "type": "object",
  "properties": {
    "keys": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "prefix": {
            "type": "string"
          },
          "owner_id": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "identity_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "created_at": {
            "type": "number"
          },
          "last_used_at": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "revoked_at": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "expires_at": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "made_by": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "prefix",
          "owner_id",
          "scopes",
          "identity_ids",
          "created_at",
          "last_used_at",
          "revoked_at",
          "expires_at",
          "made_by"
        ],
        "additionalProperties": false
      }
    },
    "limit": {
      "type": "number"
    },
    "live": {
      "type": "number"
    }
  },
  "required": [
    "keys",
    "limit",
    "live"
  ],
  "additionalProperties": false
}

curl -X GET 'https://api.batondeck.com/v1/workspace/keys' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"

Mint an agent key for the caller. The key is in this response and nowhere else, ever

POST /v1/workspace/keys · operation mintApiKey

Requires the batondeck:workspace:read permission (action apikey:mint).

Requires a step-up: MFA enrolled and re-authenticated within 15 minutes. Not reachable with an API key — a key has no session and so can never step up.

Refused while the workspace is suspended or on deletion hold.

Request body (application/json)

Field	Type	Required	Notes
name	string	yes	≥ 1 chars, ≤ 100 chars
scopes	array of string
everything	boolean
identity_ids	array of string
expires_in_days	integer		min 1, max 365

Request schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "scopes": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "everything": {
      "type": "boolean"
    },
    "identity_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "expires_in_days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 365
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

Responses

Status	Meaning
201	Mint an agent key for the caller. The key is in this response and nowhere else, ever
400	The arguments did not validate.
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

201 response schema

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string"
    },
    "api_key": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "prefix": {
          "type": "string"
        },
        "owner_id": {
          "type": "string"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "identity_ids": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "created_at": {
          "type": "number"
        },
        "last_used_at": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "revoked_at": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "expires_at": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "made_by": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "prefix",
        "owner_id",
        "scopes",
        "identity_ids",
        "created_at",
        "last_used_at",
        "revoked_at",
        "expires_at",
        "made_by"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "key",
    "api_key"
  ],
  "additionalProperties": false
}

curl -X POST 'https://api.batondeck.com/v1/workspace/keys' \
  -H "Authorization: Bearer $BATONDECK_API_KEY" \
  -H 'content-type: application/json' \
  -d @body.json

Revoke an agent key: the caller’s own, or any for an admin. The row stays, so the audit rows it wrote still name it

DELETE /v1/workspace/keys/{id} · operation revokeApiKey

Requires the batondeck:workspace:read permission (action apikey:revoke).

Allowed while the workspace is paused, suspended or on deletion hold: it only takes access away.

Parameters

Name	In	Type	Required	Notes
id	path	string	yes

Responses

Status	Meaning
204	Done. No body.
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

curl -X DELETE 'https://api.batondeck.com/v1/workspace/keys/:id' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"