Skip to content
Artbucket

Set up single sign-on

PUT
/api/v1/sso
curl --request PUT \
  --url http://localhost:3000/api/v1/sso \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "issuer": "https://example.com", "clientId": "example", "clientSecret": "example", "domain": "example", "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

One OpenID Connect provider (Okta, Entra ID, Google Workspace…) for the people at one email domain. Register redirectUri with the provider first, then save its issuer and client here: the endpoints are read from the issuer’s discovery document now, and a 422 says what was wrong with it. Add the TXT record in record, then POST /api/v1/sso/verify. From then on anyone at the domain signs in through the provider and joins the organization able to read projectId (the oldest project when null). A new domain is proved again; one another organization proved is refused.

Scope: admin.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
issuer
required

The provider’s issuer URL: its discovery document is read from {issuer}/.well-known/openid-configuration

string format: uri
<= 2000 characters
clientId
required

The app’s client ID at the provider

string
>= 1 characters <= 500 characters
clientSecret

The app’s client secret. Needed to set it up; left out on a change, the one kept stays

string
>= 1 characters <= 2000 characters
domain
required

The email domain its people sign in with, e.g. acme.com. Proved by a TXT record

string
>= 1 characters <= 253 characters
projectId
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
Examplegenerated
{
  "issuer": "https://example.com",
  "clientId": "example",
  "clientSecret": "example",
  "domain": "example",
  "projectId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

Responses

Section titled “Responses”

200

Section titled “200”

Single sign-on

Media typeapplication/json
object
data
required
object
issuer
required
string
clientId
required
string
domain
required
string
verified
required

The domain is proved: its people sign in through the provider

boolean
required
required

Addresses at the domain sign in only through the provider, but for the organization’s admins

boolean
projectId
required

The project its people land in the first time, able to read; null for the organization’s oldest

string | null
record
required

What proves the domain: add this record at your DNS host

object
type
required
string
Allowed value: TXT
name
required
string
value
required
string
redirectUri
required

Register this with the provider as the app’s redirect URI

string format: uri
Example
{
  "data": {
    "record": {
      "type": "TXT"
    }
  }
}

default

Section titled “default”

An error

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
detail
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": "example"
  }
}