---
title: "Accept an invitation"
method: POST
path: "/invitations/{id}/accept"
tags: ["Invitations"]
---

# Accept an invitation

`POST /invitations/{id}/accept`

## Request

- Base URL: `https://api.smokeball.com`
- URL: `https://api.smokeball.com/invitations/{id}/accept`
- Auth: API key in header `x-api-key` and API key in header `Authorization`

Server-to-server clients only. Creates the invited person's login under the invited email
address, with a user id derived from the invitation, and registers it with the firm; omit
`password` to have the identity provider email them a way to set one. Repeating the request,
even after the invitation's expiry, answers the same reply and creates the login once.

## Path parameters

- `id` string, required

## Request body

- AcceptInvitationDto: The credential the invited person's login is created with.
  - `password` string, nullable: Password with a lowercase, uppercase, numeric and special character; omit it to have the identity provider email the person a way to set one.
  - `provider` string: Where the login is created: Default (when omitted) or Auth0.
  - `mfaEnrollmentGraceDays` integer, nullable: Number of days after creation during which the user may sign in without setting up multi-factor authentication. Once the period ends, enrolment is required at the next sign-in. Between 1 and 90. Auth0 users only; ignored for other providers. When omitted: enrolment is required at the first sign-in.

## Response `202`

When the request is accepted. Returns a hypermedia 'Link' object of the user.

- Link
  - `id` string, nullable
  - `href` string, nullable
  - `relation` string, nullable
  - `method` string, nullable

## Other responses

- `400`: When the invitation expired or was cancelled ('Invitation is no longer valid'), was accepted by another login ('Invitation has already been accepted'), a login already exists for the invited email address ('Email address has already been registered'), the identity provider refused the credential or `mfaEnrollmentGraceDays` is outside 1 to 90 ('Login could not be created'), or the login is already registered with the firm ('Already registered with this firm').
- `403`: When the authenticated client is not a server-to-server client, lacks the `invitations/write` scope or carries no firm account (all bodyless).
- `404`: When no invitation with the specified id exists for this account ('Invitation not found').

## Changes

- **2026-10-15** `77592e907e3d`: 3 info
  - added the new optional request property `allOf[#/components/schemas/AcceptInvitationDto]/mfaEnrollmentGraceDays` (media type: application/json-patch+json)
  - added the new optional request property `allOf[#/components/schemas/AcceptInvitationDto]/mfaEnrollmentGraceDays` (media type: application/json)
  - added the new optional request property `allOf[#/components/schemas/AcceptInvitationDto]/mfaEnrollmentGraceDays` (media type: application/*+json)
- **2026-10-02** `2f6c7f5744a8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/smokeball/apis/smokeball-api/changes/invitations/:id/accept/post.md)

---

[API](https://skmtc.dev/smokeball/apis/smokeball-api.md) - [All operations](https://skmtc.dev/smokeball/apis/smokeball-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smokeball/apis/smokeball-api/revisions/6e350cf667d4?raw)