Skip to content
KataraKatara documentation

Invite a person by email address

POST
/katara/v1/orgs/{org_id}/invitations
curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/invitations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --header 'X-Katara-CSRF: 1' \
  --data '{ "email": "[email protected]", "role": "admin", "expires_in_seconds": 1 }'

Requires organization member administration permission. Give either email or user_id, never both. Katara emails an invitation link to the address and reports whether it did in email_sent; a failed send leaves the invitation in place. The one-time token is returned on the reply that creates the invitation and never again, so the link can be shared by hand if the email does not arrive. Creating an email invitation does not look up accounts: the reply is the same whether or not the address has one. An invitation by user ID raises an in-app notice for that account instead of an email. Repeating the same request key returns the original operation without a token and sends nothing.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
required
string
/^[A-Za-z0-9._:-]{8,128}$/
X-Katara-CSRF
Allowed value: 1

Browser cookie mutations require value 1 and an allowed Origin. Session bearer clients may omit this header.

X-Katara-Account-ID
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Required for cookie-authenticated changes. Use the UUID of the account that loaded the application. A different current cookie account returns account_changed before the handler runs. Session bearer and API key clients do not require this header.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
One of:
object
email
required

The address the invitation is emailed to. Printable ASCII; stored trimmed and lowercased. Only a signed-in account with this confirmed address can accept the invitation.

string format: email
>= 3 characters <= 254 characters
role
required
Allowed values: admin builder operator reviewer viewer billing
expires_in_seconds
required
integer
>= 60 <= 604800

Responses

Section titled “Responses”

201

Section titled “201”

Successful request

Media typeapplication/json

An invitation names either an email address or a user ID. The token is returned once, on the reply that created the invitation.

object
operation_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
resource_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
completed
required
boolean
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
user_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
email
string format: email
>= 3 characters <= 254 characters
role
required
Allowed values: admin builder operator reviewer viewer billing
expires_at
required
string format: date-time
token
string
/^[A-Za-z0-9_-]{43}$/
email_sent
required

Whether Katara emailed the invitation link. Always false for an invitation by user ID and for a repeated request. The token is still returned on the first reply, so the link can be shared another way.

boolean
Example
{
  "role": "admin"
}

409

Section titled “409”

Account_changed: reload and review with the signed-in account. invitation_open: the address already has an open invitation to this organization; revoke it to send a new one.

429

Section titled “429”

Invitation_limit_reached: the organization has created 100 invitations in the last 24 hours.

default

Section titled “default”

Request error

Media typeapplication/json
object
error
required
object
message
required
string
>= 1 characters <= 500 characters
type
required
string
>= 1 characters <= 100 characters
code
required

Stable; branch on it. Any operation can answer invalid_request, with param naming the refused field when there is one; human_session_required, when an API key, service account or workload calls an operation only a signed-in person may perform; reauthentication_required, when a person’s sign-in is too old for the operation; permission_denied; route_not_found and method_not_allowed, when no operation matches the path or method; and feature_unavailable, when the operation’s service is not enabled on this deployment.

string
>= 1 characters <= 100 characters
param
required

The request field a refusal is about, such as the agent_id or run_id query parameter; null when the refusal is not about one field.

string | null
request_id
required
string
>= 1 characters <= 100 characters
upstream_status
required
integer | null
action
Allowed values: sign_in reauthenticate request_access review fund retry reconcile refresh support
operation_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
snapshot_ref
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
Example
{
  "error": {
    "action": "sign_in"
  }
}