Identity: grants

Which owners may act as this identity. Several is a shared inbox (SPEC §3.3)

GET /v1/identities/{slug}/grants · operation listIdentityGrants

Requires the batondeck:identities:read permission (action identity:read).

Parameters

Name	In	Type	Required	Notes
slug	path	string	yes

Responses

Status	Meaning
200	Which owners may act as this identity. Several is a shared inbox (SPEC §3.3)
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": {
    "grants": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "owner_id": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "created_at": {
            "type": "number"
          }
        },
        "required": [
          "owner_id",
          "role",
          "created_at"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "grants"
  ],
  "additionalProperties": false
}

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

Let another owner act as this identity, which is how a shared inbox is made

POST /v1/identities/{slug}/grants · operation grantIdentity

Requires the batondeck:identities:manage permission (action identity:grant).

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.

Parameters

Name	In	Type	Required	Notes
slug	path	string	yes

Request body (application/json)

Field	Type	Required	Notes
owner_id	string	yes	≥ 1 chars

Request schema

{
  "type": "object",
  "properties": {
    "owner_id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "owner_id"
  ],
  "additionalProperties": false
}

Responses

Status	Meaning
200	Let another owner act as this identity, which is how a shared inbox is made
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.

200 response schema

{
  "type": "object",
  "properties": {
    "owner_id": {
      "type": "string"
    },
    "role": {
      "type": "string"
    },
    "created_at": {
      "type": "number"
    }
  },
  "required": [
    "owner_id",
    "role",
    "created_at"
  ],
  "additionalProperties": false
}

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

Take back an owner’s access to this identity

DELETE /v1/identities/{slug}/grants/{ownerId} · operation revokeIdentityGrant

Requires the batondeck:identities:manage permission (action identity:revoke).

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.

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

Parameters

Name	In	Type	Required	Notes
slug	path	string	yes
ownerId	path	string	yes

Responses

Status	Meaning
200	Take back an owner’s access to this identity
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": {
    "revoked": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "revoked"
  ],
  "additionalProperties": false
}

curl -X DELETE 'https://api.batondeck.com/v1/identities/:slug/grants/:ownerId' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"