Invites

An invite asks one email address to join a workspace with a role and, optionally, teams. Its emailed link holds a secret token, and accepting it makes the person a member.

The Invite object

An invitation for one email address to join the workspace.

Attributes

idstringRequired

Unique ID of the invite.

workspaceIdstringRequired

Unique ID of the workspace.

emailstringRequired

The lowercased email address the invite was sent to.

rolestringRequired

The role the person gets on accepting: admin, member or viewer.

One ofowneradminmemberviewer

invitedByUserIdnullable stringRequired

The user who sent the invite, or null when an account API key sent it.

expiresAtstringRequired

When the invite link stops working, as an ISO 8601 timestamp: 7 days after it was sent.

acceptedAtnullable stringRequired

When the invite was accepted, as an ISO 8601 timestamp; null until then.

revokedAtnullable stringRequired

When the invite was revoked, as an ISO 8601 timestamp; null unless revoked.

createdAtstringRequired

When the invite was created, as an ISO 8601 timestamp.

updatedAtstringRequired

When the invite last changed, as an ISO 8601 timestamp.

teamsarray of objectsRequired

The teams the person joins on accepting.

The Invite object

{  "id": "Iv6WqR3nTb8K",  "workspaceId": "Wk7Qm2RtXa9L",  "email": "lee@acme.dev",  "role": "member",  "invitedByUserId": "Us3NfP8kLq2V",  "expiresAt": "2026-10-21T09:05:12.000Z",  "acceptedAt": null,  "revokedAt": null,  "createdAt": "2026-10-14T09:05:12.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "teams": [    {      "inviteId": "Iv6WqR3nTb8K",      "teamId": "Tm6PzN3kWq1J",      "teamName": "Web"    }  ]}

Get an invite by token

GET/v1/invites/{token}

Returns the invite a link points to, including expired, revoked and accepted ones, so a person can see which workspace invited them. It needs no API key. Returns invite: null when no invite has the token.

Path parameters

tokenstringRequired

The secret token from the invite link, the last part of /invite/{token}.

Returns

Returns an object with these fields. Status 200.

invitenullable objectRequired

The invite the token belongs to, or null when there is none.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

GET/v1/invites/{token}

1curl https://api.qa.clankership.net/v1/invites/{token}

Response200

{  "invite": {    "id": "Iv6WqR3nTb8K",    "email": "lee@acme.dev",    "role": "member",    "workspaceId": "Wk7Qm2RtXa9L",    "workspaceName": "Acme",    "workspaceSlug": "acme",    "expiresAt": "2026-10-21T09:05:12.000Z",    "acceptedAt": null,    "revokedAt": null,    "teams": [      {        "teamId": "Tm6PzN3kWq1J",        "teamName": "Web"      }    ]  }}

List invites

GET/v1/workspaces/{slug}/invites

Returns the workspace's open invites: those not accepted or revoked, including expired ones. Any member can list invites.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

Returns

Returns an array of Invite objects. Status 200.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

GET/v1/workspaces/{slug}/invites

1curl https://api.qa.clankership.net/v1/workspaces/acme/invites \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

[  {    "id": "Iv6WqR3nTb8K",    "workspaceId": "Wk7Qm2RtXa9L",    "email": "lee@acme.dev",    "role": "member",    "invitedByUserId": "Us3NfP8kLq2V",    "expiresAt": "2026-10-21T09:05:12.000Z",    "acceptedAt": null,    "revokedAt": null,    "createdAt": "2026-10-14T09:05:12.000Z",    "updatedAt": "2026-10-14T09:05:12.000Z",    "teams": [      {        "inviteId": "Iv6WqR3nTb8K",        "teamId": "Tm6PzN3kWq1J",        "teamName": "Web"      }    ]  }]

Create invites

POST/v1/workspaces/{slug}/invites

Invites each address with the same role and teams, queues an email with a link that expires in 7 days, and revokes any older open invite to that address. Only owners and admins can invite. Addresses are invited in order and the first failure stops the request, keeping the invites already made.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

Body parameters

emailsarray of stringsRequired

The email addresses to invite. An address repeated exactly is invited once.

rolestringRequired

The role each person gets: admin, member or viewer. Owner is refused.

One ofowneradminmemberviewer

teamIdsarray of stringsRequired

IDs of teams each person joins on accepting. Send [] for none.

Returns

Returns an object with these fields. Status 200.

resultsarray of objectsRequired

One entry per invited address, in request order.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

POST/v1/workspaces/{slug}/invites

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/invites \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "emails": [6      "lee@acme.dev"7    ],8    "role": "member",9    "teamIds": [10      "Tm6PzN3kWq1J"11    ]12  }'

Response200

{  "results": [    {      "email": "lee@acme.dev",      "ok": true    }  ]}

Revoke an invite

POST/v1/workspaces/{slug}/invites/{inviteId}/revoke

Cancels the invite so its link stops working, and records an invite.revoked event. Only owners and admins can revoke invites.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

inviteIdstringRequired

The invite's ID, such as Iv6WqR3nTb8K.

Returns

Returns an object with these fields. Status 200.

okbooleanRequired

Always true: the change was made.

Always true

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

POST/v1/workspaces/{slug}/invites/{inviteId}/revoke

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/invites/{inviteId}/revoke \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "ok": true}

Change an invite's role

PATCH/v1/workspaces/{slug}/invites/{inviteId}

Sets the role an open invite grants and records an invite.role_changed event. Only owners and admins can change it.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

inviteIdstringRequired

The invite's ID, such as Iv6WqR3nTb8K.

Body parameters

rolestringRequired

The role the person gets: admin, member or viewer. Owner is refused.

One ofowneradminmemberviewer

Returns

Returns an object with these fields. Status 200.

okbooleanRequired

Always true: the change was made.

Always true

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

PATCH/v1/workspaces/{slug}/invites/{inviteId}

1curl -X PATCH https://api.qa.clankership.net/v1/workspaces/acme/invites/{inviteId} \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "role": "viewer"6  }'

Response200

{  "ok": true}

Resend an invite

POST/v1/workspaces/{slug}/invites/{inviteId}/resend

Queues a new email with a fresh link that expires in 7 days; the old link stops working. Records an invite.resent event. Only owners and admins can resend open invites.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

inviteIdstringRequired

The invite's ID, such as Iv6WqR3nTb8K.

Returns

Returns an object with these fields. Status 200.

okbooleanRequired

Always true: the change was made.

Always true

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

POST/v1/workspaces/{slug}/invites/{inviteId}/resend

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/invites/{inviteId}/resend \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "ok": true}

Accept an invite

POST/v1/invites/{token}/accept

Adds you to the workspace with the invite's role and teams, and marks the invite accepted. Your email address must match the invite's. Fails with NotFound when the invite is expired, revoked or already accepted.

Path parameters

tokenstringRequired

The secret token from the invite link, the last part of /invite/{token}.

Returns

Returns an object with these fields. Status 200.

okbooleanRequired

Always true: you joined the workspace.

Always true

workspaceSlugstringRequired

The slug of the workspace you joined, such as acme.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

POST/v1/invites/{token}/accept

1curl -X POST https://api.qa.clankership.net/v1/invites/{token}/accept \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "ok": true,  "workspaceSlug": "acme"}

NextEvents