Accept an Invitation

POST

/v1/invitations/accept

curl --request POST \
  --url https://app.caprid.com/v1/invitations/accept \
  --header 'Content-Type: application/json' \
  --cookie __Host-switchboard_session=<__Host-switchboard_session> \
  --data '{ "secret": "sbi_mR3x9Qe2vT8wY1zA4bC7dF0gH5jK6lN2pS8uV3xZ1qW" }'

Makes you a Member of the Organization, with the role the Invitation names. Your email has to be the one invited, even if you have the link. Each Invitation can be accepted once.

Send secret, the last part of the link (/app/invitations/{secret}). With WorkOS login, which has verified your email, you can send the Invitation’s id instead. Without WorkOS, nothing has verified your email, so only the link works.

This takes a session. An API key belongs to an Organization, not a person.

Authorizations

• session

Request Body^required

Media typeapplication/json

object

secret

The secret from the Invitation’s link.

string

id

The Invitation’s id. Only with WorkOS login.

string

Example

{
  "secret": "sbi_mR3x9Qe2vT8wY1zA4bC7dF0gH5jK6lN2pS8uV3xZ1qW"
}

Responses

200

The Organization you joined.

Media typeapplication/json

A customer of Switchboard. It owns its Namespaces, and the API keys, Nodes and enrollments that serve them. Its Members manage all of it.

object

id

required

Identifies the Organization in routes. It never changes.

integer

name

required

For display. Any Member can change it.

string

role

Your role in it. Absent for an API key, which has none.

string

Allowed values: owner member

created_at

required

integer

trial_expires_at

When a Trial Organization lapses, so its Agent knows how long it has to get a person to claim it. Absent for every other Organization.

integer

Example

{
  "id": 4,
  "name": "Acme",
  "role": "member",
  "created_at": 1790294400
}

400

The request is malformed or a field is invalid. The message says which.

Media typeapplication/json

object

error

required

string

Example

{
  "error": "the requested grants exceed the key's scope"
}

401

No valid credential. Missing, expired and revoked credentials all get the same response, and so does an API key whose trial has lapsed. An Agent token from before a claim gets a 401 too, once the claim has made the trial a person’s, with a message saying to get a new token.

Media typeapplication/json

object

error

required

string

Example

{
  "error": "the requested grants exceed the key's scope"
}

Headers

WWW-Authenticate

string

Example

Bearer realm="switchboard"

403

The Invitation is for another email address, you sent an id on a server that hasn’t verified your email, or you sent an API key.

Media typeapplication/json

object

error

required

string

Example

{
  "error": "this invitation is for another email address: sign in as the address it was sent to"
}

404

No such Invitation.

Media typeapplication/json

object

error

required

string

Example

{
  "error": "the requested grants exceed the key's scope"
}

409

You’re already a Member of that Organization.

Media typeapplication/json

object

error

required

string

Example

{
  "error": "the requested grants exceed the key's scope"
}

410

The Invitation has already been used, was revoked, or has expired. Ask for a new one.

Media typeapplication/json

object

error

required

string

Example

{
  "error": "this invitation has expired"
}