Operation

Invite User

POST/users/invitations

Send an invitation to someone to join your organisation. The person will receive an email with a link to accept the invitation and set up their account. You can pre-assign roles so they'll have the right access from day one. Invitations expire after 7 days. If someone hasn't accepted by then, you can resend it.

When to use this

Adding new team members to your organisation
Inviting external collaborators with limited access
Onboarding staff with pre-assigned roles

Headers

Idempotency-KeystringOptional: Makes the write safe to retry. The first request with a key does the work and its response is stored for 24 hours; a repeat with the same key and the same request (method, path, query, X-Ticketlayer-Channel, TL-Version and body) gets that stored status and body back, marked `Idempotent-Replay: true`, without running again. The key is scoped to your organisation and your credential. The same key with a different request is 422 IDEMPOTENCY_KEY_REUSED; a repeat while the first is still running waits for it, then answers 409 IDEMPOTENT_REQUEST_IN_PROGRESS if it has not finished. Only a 2xx is stored: after an error the key is free again. Omit the header and the request behaves as it always has.

Body

Returns

Invitation created successfully

Errors

400: Bad Request - Invalid input
401: Unauthorized - Authentication required
403: Forbidden - Insufficient permissions
404: Not Found - Resource not found
500: Internal Server Error

Every error names its code and links to it. All error codes

Notes

Note

The invitation email is sent automatically-you don't need to send it yourself.

Tip

Assign roles when creating the invitation so the user has the right permissions immediately after accepting.

import { BackstageClient } from '@ticketlayer/backstage';const client = new BackstageClient({  organisationSlug: 'your-org',});client.setAccessToken('YOUR_ACCESS_TOKEN');// Create userinvitationconst userinvitation = await client.userinvitation.create({  name: 'New UserInvitation',  // Add other required fields});console.log(`Created userinvitation with ID: ${userinvitation.id}`);

Response 201

{
  "invitation": {
    "id": "inv_abc123",
    "organisationId": "org_xyz789",
    "userId": "usr_pending123",
    "code": "inv_BvQ8mK...",
    "email": "newuser@example.com",
    "expiresAt": "2024-01-08T00:00:00.000Z",
    "redeemedAt": null,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}