Skip to content
HDTPHDTP Docs

Identity: invites

View as Markdown
Section titled “Invites this identity has issued. Each carries its link where the token was kept, and only for a caller who may mint an invite (contact:write)”

GET /v1/identities/{slug}/invites · operation listInvites

Requires the batondeck:contacts:read permission (action contact:read).

Parameters

Name In Type Required Notes
slug path string yes

Responses

Status Meaning
200 Invites this identity has issued. Each carries its link where the token was kept, and only for a caller who may mint an invite (contact:write)
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": {
    "invites": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "preset": {
            "type": "string"
          },
          "uses": {
            "type": "number"
          },
          "max_uses": {
            "type": "number"
          },
          "auto_accept": {
            "type": "boolean"
          },
          "expires_at": {
            "type": "number"
          },
          "revoked_at": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "label",
          "preset",
          "uses",
          "max_uses",
          "auto_accept",
          "expires_at",
          "revoked_at",
          "url"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "invites"
  ],
  "additionalProperties": false
}
Terminal window
curl -X GET 'https://api.batondeck.com/v1/identities/:slug/invites' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"
Section titled “Mint an invite. The link is in the answer, and listInvites answers it again, to a caller who may mint one, for as long as the row exists”

POST /v1/identities/{slug}/invites · operation createInvite

Requires the batondeck:contacts:manage permission (action contact:write).

Refused while the workspace is suspended or on deletion hold.

Accepts an Idempotency-Key header. A repeat within 24 hours returns the first answer; the same key with different arguments is refused with idempotency_mismatch.

Parameters

Name In Type Required Notes
slug path string yes
Idempotency-Key header string Repeat this value to retry the call without repeating its effect.

Request body (application/json)

Field Type Required Notes
label string yes ≤ 128 chars, default “”
preset “basic” \ “colleague” \ “close” \
max_uses integer yes 1 for one-time, 0 for unlimited. min 0, max 1000, default 1
auto_accept boolean yes default false
expires_in_days integer yes min 1, max 90, default 14
Request schema 
{
  "type": "object",
  "properties": {
    "label": {
      "default": "",
      "type": "string",
      "maxLength": 128
    },
    "preset": {
      "default": "basic",
      "type": "string",
      "enum": [
        "basic",
        "colleague",
        "close",
        "muted"
      ]
    },
    "max_uses": {
      "description": "1 for one-time, 0 for unlimited",
      "default": 1,
      "type": "integer",
      "minimum": 0,
      "maximum": 1000
    },
    "auto_accept": {
      "default": false,
      "type": "boolean"
    },
    "expires_in_days": {
      "default": 14,
      "type": "integer",
      "minimum": 1,
      "maximum": 90
    }
  },
  "required": [
    "label",
    "preset",
    "max_uses",
    "auto_accept",
    "expires_in_days"
  ],
  "additionalProperties": false
}

Responses

Status Meaning
201 Mint an invite. The link is in the answer, and listInvites answers it again, to a caller who may mint one, for as long as the row exists
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.
422 That Idempotency-Key was used with different arguments.
201 response schema 
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "expires_at": {
      "type": "number"
    }
  },
  "required": [
    "id",
    "url",
    "expires_at"
  ],
  "additionalProperties": false
}
Terminal window
curl -X POST 'https://api.batondeck.com/v1/identities/:slug/invites' \
  -H "Authorization: Bearer $BATONDECK_API_KEY" \
  -H 'content-type: application/json' \
  -d @body.json
Section titled “Accept somebody else’s invite link: this identity becomes their contact”

POST /v1/identities/{slug}/invites/redeem · operation redeemInvite

Requires the batondeck:contacts:manage permission (action contact:write).

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
url string yes ≥ 12 chars, ≤ 2048 chars
Request schema 
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "minLength": 12,
      "maxLength": 2048
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}

Responses

Status Meaning
201 Accept somebody else’s invite link: this identity becomes their contact
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.
429 This identity’s outbound budget (HDTP §12: 1 call a second per contact with a burst of 10, the identity’s aggregate, 20 an hour to strangers), or the peer’s own, refused the call; retry_after and Retry-After say when to try again.
201 response schema 
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "accepted",
        "pending"
      ]
    },
    "contact": {
      "type": "object",
      "properties": {
        "fingerprint": {
          "type": "string"
        },
        "endpoint": {
          "type": "string"
        },
        "display_name": {
          "type": "string"
        }
      },
      "required": [
        "fingerprint",
        "endpoint",
        "display_name"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "status",
    "contact"
  ],
  "additionalProperties": false
}
Terminal window
curl -X POST 'https://api.batondeck.com/v1/identities/:slug/invites/redeem' \
  -H "Authorization: Bearer $BATONDECK_API_KEY" \
  -H 'content-type: application/json' \
  -d @body.json

Revoke an invite; a revoked token is indistinguishable from one that never existed

Section titled “Revoke an invite; a revoked token is indistinguishable from one that never existed”

DELETE /v1/identities/{slug}/invites/{id} · operation revokeInvite

Requires the batondeck:contacts:manage permission (action contact:write).

Refused while the workspace is suspended or on deletion hold.

Parameters

Name In Type Required Notes
slug path string yes
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.
Terminal window
curl -X DELETE 'https://api.batondeck.com/v1/identities/:slug/invites/:id' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"