Create an Account

POST

/v1/signup

curl --request POST \
  --url https://app.caprid.com/v1/signup \
  --header 'Content-Type: application/json' \
  --data '{ "email": "dev@acme.example", "password": "correct horse battery staple", "namespace": "acme" }'

Creates an Account. Every Account starts by doing one of two things:

• Creating an Organization. Send namespace. The Organization is named after the Namespace (you can rename it later), you are its Owner, and the response carries its first API key. This is the only time that key’s secret is shown, so store it now.
• Joining one. Send invitation instead, and you become a Member of the Organization that invited you, with the role it invited you as. You get no API key, because the Organization already has its own. Without WorkOS login, send the secret from the Invitation’s link, because nothing has verified your email. With WorkOS login, send the Invitation’s id from GET /v1/signup.

The response also sets a session cookie, for a signup that came from the dashboard.

Password signups are limited to 20 an hour from each client address.

With WorkOS login, the body needs only namespace or invitation. The email is the one WorkOS verified, there is no password, and the request has to carry the cookie the login callback set.

Request Body^required

Media typeapplication/json

Send namespace or invitation. email and password are required too, unless the server uses WorkOS login.

object

email

Stored lowercased. Alice@example.com and alice@example.com are the same Account.

string format: email

<= 254 characters

password

Length is the only rule. Counted in characters, not bytes.

string

>= 12 characters <= 1024 characters

namespace

A Namespace’s name, which is the root of every path signed for it. It never changes. Use lowercase letters, digits and hyphens, and start and end with a letter or digit. Some names, like admin and default, are reserved, and so is every name that starts with trial-, which only Trial Organizations get.

string

>= 3 characters <= 32 characters /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/

invitation

Join the Organization this Invitation is for, instead of creating one. Send the secret from its link, or with WorkOS login, its id. Your email has to be the one invited.

string

Examples

Create an Organization

{
  "email": "dev@acme.example",
  "password": "correct horse battery staple",
  "namespace": "acme"
}

Join with an Invitation's link

{
  "email": "alice@acme.example",
  "password": "correct horse battery staple",
  "invitation": "sbi_mR3x9Qe2vT8wY1zA4bC7dF0gH5jK6lN2pS8uV3xZ1qW"
}

Responses

201

The Account, and when it created an Organization, that Organization’s first API key with its secret.

Media typeapplication/json

object

account

required

object

email

The person signed in. Absent for an API key.

string format: email

created_at

When the person signed up. Absent for an API key.

integer

api_key

The API key making the call, with its namespaces limit if it has one. A limited key can’t list its Organization’s Namespaces, so this is how it finds the ones it can reach. Absent for a session.

object

id

required

Identifies the key for revoking it. Not a secret.

string

label

required

string

preview

required

The first 6 characters of the secret after sb_, so you can tell keys apart.

string

created_at

required

integer

expires_at

Absent for a key that never expires.

integer

last_used_at

Absent for a key that has never been used.

integer

namespaces

The Namespaces the key is limited to, by name. Absent for a key with no limit. A deleted Namespace drops out, so a key whose Namespaces have all been deleted has [] here and can do nothing.

Array<string>

organizations

required

Array<object>

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

namespace

The one Namespace you can reach, as this reported before Organizations. Absent unless you reach exactly one.

string

>= 3 characters <= 32 characters /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/

platform_peering

That Namespace’s platform_peering. Absent along with namespace.

boolean

api_key

object

id

required

Identifies the key for revoking it. Not a secret.

string

label

required

string

preview

required

The first 6 characters of the secret after sb_, so you can tell keys apart.

string

created_at

required

integer

expires_at

Absent for a key that never expires.

integer

last_used_at

Absent for a key that has never been used.

integer

namespaces

The Namespaces the key is limited to, by name. Absent for a key with no limit. A deleted Namespace drops out, so a key whose Namespaces have all been deleted has [] here and can do nothing.

Array<string>

secret

required

The API key itself. Shown only in this response.

string

Example

{
  "account": {
    "api_key": {
      "id": "3f9a1c07be42",
      "namespaces": [
        "acme-staging"
      ]
    },
    "organizations": [
      {
        "id": 4,
        "name": "Acme",
        "role": "owner",
        "trial_expires_at": 1760604800
      }
    ],
    "namespace": "acme"
  },
  "api_key": {
    "id": "3f9a1c07be42",
    "namespaces": [
      "acme-staging"
    ],
    "secret": "sb_R2x0Z9kQ7mVt3xLp8wNc1bYh5sDf2gJr6uEa0zWiTq4"
  }
}

Headers

Set-Cookie

string

__Host-switchboard_session over HTTPS, switchboard_session over plain HTTP: HttpOnly, SameSite=Lax, Path=/, valid for 14 days.

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

With WorkOS login, there is no signup in progress. Sign in at /app/ first.

Media typeapplication/json

object

error

required

string

Example

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

403

The Invitation is for another email address.

Media typeapplication/json

object

error

required

string

Example

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

404

No such Invitation.

Media typeapplication/json

object

error

required

string

Example

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

409

The email or the Namespace is already taken.

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"
}

429

Rate limited. Try again later.

Media typeapplication/json

object

error

required

string

Example

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