Invite someone
const url = 'https://app.caprid.com/v1/organizations/4/invitations';const options = { method: 'POST', headers: { cookie: '__Host-switchboard_session=<__Host-switchboard_session>', 'Content-Type': 'application/json' }, body: '{"email":"alice@acme.example","role":"member"}'};
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://app.caprid.com/v1/organizations/4/invitations \ --header 'Content-Type: application/json' \ --cookie __Host-switchboard_session=<__Host-switchboard_session> \ --data '{ "email": "alice@acme.example", "role": "member" }'Invites one email address into the Organization, and returns a link for that person. Switchboard sends no email, so copy the link and send it yourself. Only the person with that email can use the link, so it’s safe if someone forwards it by mistake.
The link works once, and expires after 7 days. Its secret is shown only in this response.
Owners only, signed in with a session. An API key can never invite anyone, so a leaked one can’t be used to let its holder in.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The Organization’s id, from GET /v1/organizations.
Example
4Request Bodyrequired
Section titled “Request Bodyrequired”object
Matched without regard to case.
The role they’ll have once they accept.
Example
{ "email": "alice@acme.example", "role": "member"}Responses
Section titled “Responses”The Invitation, with its link.
An Invitation just created, with its link. The link’s secret is shown only here.
object
Identifies the Invitation in routes. Not a secret.
The Organization’s name, for someone who isn’t in it yet.
Who may accept it. Stored lowercased.
The role they’ll have once they accept.
When the link stops working, 7 days after it was created.
The secret the link carries. Send it to POST /v1/invitations/accept.
The dashboard page that accepts it. Send this to the person you invited.
Example
{ "id": "3f9c1a2b7d4e", "organization_id": 4, "organization_name": "Acme", "email": "alice@acme.example", "role": "owner", "created_at": 1790294400, "expires_at": 1790899200, "secret": "sbi_mR3x9Qe2vT8wY1zA4bC7dF0gH5jK6lN2pS8uV3xZ1qW", "link": "https://app.caprid.com/app/invitations/sbi_mR3x9Qe2vT8wY1zA4bC7dF0gH5jK6lN2pS8uV3xZ1qW"}The request is malformed or a field is invalid. The message says which.
object
Example
{ "error": "the requested grants exceed the key's scope"}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.
object
Example
{ "error": "the requested grants exceed the key's scope"}Headers
Section titled “Headers”Example
Bearer realm="switchboard"You aren’t an Owner of this Organization, or you sent an API key.
object
Example
{ "error": "only an Owner can manage this Organization's Invitations"}No such thing, or not yours. Another customer’s Organization or Namespace is a 404 too, so nobody can tell which ones exist.
object
Example
{ "error": "the requested grants exceed the key's scope"}That email already belongs to a Member.
object
Example
{ "error": "that email already belongs to a Member of this organization"}