Invite someone to the domain

POST

/domains/{domain}/invites

const url = 'https://api.nsin.cloud/domains/example.com/invites';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"email":"hello@example.com","role":"admin","expires_in_hours":1}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.nsin.cloud/domains/example.com/invites \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "email": "hello@example.com", "role": "admin", "expires_in_hours": 1 }'

Creates an invitation and emails it.

An invite is bound to the address it was sent to: forwarding the email does not let someone else accept it. Requires members.manage.

Authorizations

bearerAuth
apiKeyAuth

Parameters

Path Parameters

domain

required

string

The domain name (for example example.com) — not a numeric id.

Example

example.com

Request Body^required

application/json

object

email

required

string format: email

role

required

A role that may be assigned to a member or invitation. owner is not grantable — it always follows domain ownership.

string

Allowed values: admin editor viewer

expires_in_hours

Lifetime of the invitation. Omit for the default.

integer

Responses

200

Invitation created, with its accept link.

application/json

object

integer

domain_id

integer

email

The address the invitation is bound to.

string

role

A role that may be assigned to a member or invitation. owner is not grantable — it always follows domain ownership.

string

Allowed values: admin editor viewer

invited_by

User id of the inviter.

integer

expires_at

string format: date-time

max_uses

integer

uses

integer

revoked_at

string format: date-time

created_at

string format: date-time

link

The accept URL. Returned when the invitation is created or resent.

string

is_link

True for a shareable link rather than an emailed invitation.

boolean

exhausted

True when uses has reached max_uses.

boolean

Example

{
  "role": "admin"
}

400

Invalid body, an invalid role, a missing or malformed email, an attempt to invite yourself, or an attempt to invite the domain’s owner.

application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object

error

required

Human-readable description of what went wrong.

string

code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

A panel session — not an API key — can additionally see session_check_failed on a 503, which means the session could not be verified, not that it is invalid. Retry it; do not discard the token.

string

Example

{
  "error": "read-only API key"
}

401

Missing, malformed, revoked or expired API key, or a key whose owning user row is gone. A key whose owning account has merely been deactivated is not this: that is 403 with code: account_suspended, because the credential itself is intact and re-issuing it changes nothing.

application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object

error

required

Human-readable description of what went wrong.

string

code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

string

Examples

invalidKey

{
  "error": "invalid API key"
}

403

The key is read-only, your role on the domain lacks the required permission, the domain’s plan does not include the feature, or the account that owns the key has been deactivated — that last one carries code: account_suspended and can arrive on any endpoint, including ones that document no 403 of their own.

application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object

error

required

Human-readable description of what went wrong.

string

code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

string

Example

{
  "error": "read-only API key"
}

404

No such domain, or it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.

application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object

error

required

Human-readable description of what went wrong.

string

code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

string

Example

{
  "error": "read-only API key"
}

409

That user is already a member.

application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object

error

required

Human-readable description of what went wrong.

string

code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

string

Example

{
  "error": "read-only API key"
}

429

The key exceeded its request budget (300 requests per minute by default).

application/json

The error shape used by every endpoint. error is always present. code is present only on the failures that have one — do not require it, and do not parse error to recover it.

object

error

required

Human-readable description of what went wrong.

string

code

Stable machine-readable reason. Present on some failures only; the wording of error may change, this will not.

account_suspended — 403. The account behind the credential has been switched off, by an admin or by its provider. Every authenticated route answers this, so treat it as terminal rather than retrying.
domain_disabled — 409, not 403. You have every right to the operation; the domain is simply switched off and is not being served, so its configuration cannot change. It stays readable, and writes work again once it is enabled.
managed_by_reseller — 403. The account is a reseller’s client and this surface belongs to its provider. See If your account is managed by a reseller.
invite_email_mismatch — 403 from POST /invites/{token}/accept. The invitation was addressed to a different email; the body also carries invited_email, masked.

string

Examples

limited

{
  "error": "rate limit exceeded"
}

Invite someone to the domain

Authorizations

Parameters

Path Parameters

Example

Request Body required

Responses

200

Example

400

Example

401

Examples

403

Example

404

Example

409

Example

429

Examples

Request Body^required