API by area

Sign-in and OAuth

47 endpoints. Paths are relative to https://api.sandscale.dev; values in braces are ones you fill in.

API reference · Authentication · Errors

MethodPathWhat it does
GET/.well-known/jwks.jsonServes the published signing keys (the active, next and retiring keys) with the keyset's cache lifetime: a next key is published at least twice that long before it signs, so a relying party that honours the header always holds the key of any ID token it is shown.
GET/.well-known/oauth-authorization-serverServes the OAuth 2.0 authorization server metadata (RFC 8414): the OpenID discovery document with the grants and client authentication methods the token endpoint accepts. MCP clients read it after the sandbox MCP server's protected resource metadata names this server.
GET/.well-known/openid-configurationServes the OpenID Provider metadata. On an Organization's sign-in host the issuer and every endpoint are that host's, so a relying party configured with that issuer validates the document.
GET/api/v1/applicationsList applications
POST/api/v1/applicationsCreate an application
GET/api/v1/applications/{clientId}Get one application
PATCH/api/v1/applications/{clientId}Update one application
DELETE/api/v1/applications/{clientId}Delete one application
GET/api/v1/applications/{clientId}/{view}One API (clientId "apis"), an application's logs or its grants.
PUT/api/v1/applications/{clientId}/apis/{apiId}Replace one api
DELETE/api/v1/applications/{clientId}/apis/{apiId}Delete one api
POST/api/v1/applications/{clientId}/secret/rotateCreate a rotate
GET/api/v1/applications/apisList apis
POST/api/v1/applications/apisCreate an api
PATCH/api/v1/applications/apis/{apiId}Update one api
DELETE/api/v1/applications/apis/{apiId}Delete one api
POST/api/v1/auth/loginCreate a login
POST/api/v1/auth/login/step-upCreate a step up
POST/api/v1/auth/login/step-up/resendCreate a resend
POST/api/v1/auth/logoutCreate a logout
POST/api/v1/auth/passkeys/authenticate/beginCreate a begin
POST/api/v1/auth/passkeys/authenticate/completeCreate a complete
POST/api/v1/auth/password/changeCreate a change
POST/api/v1/auth/password/validateCreate a validate
POST/api/v1/auth/recovery-code/verifyCreate a verify
POST/api/v1/auth/sessions/revokeCreate a revoke
POST/api/v1/auth/sessions/revoke-allCreate a revoke all
POST/api/v1/auth/token/introspectImplements RFC 7662 token introspection. The caller must authenticate as a confidential OAuth client (client_secret_basic, or client_id and client_secret in the form). Agent tokens and delegated tokens are reported active only to a resource server of their organization, with their effective scope, aud, act, org_id, token_use and consent_id.
POST/api/v1/auth/token/refreshCreate a refresh
POST/api/v1/auth/token/revokeCreate a revoke
POST/api/v1/oauth2/authorization-detailsCreate an authorization detail
GET/api/v1/oauth2/authorization-details/{clientId}Get one authorization detail
DELETE/api/v1/oauth2/authorization-details/{id}Delete one authorization detail
GET/api/v1/oauth2/clientsList clients
GET/oauth2/authorizeList authorize
POST/oauth2/authorizeCreate an authorize
POST/oauth2/deviceCreate a device
POST/oauth2/device/authorizeCreate an authorize
POST/oauth2/device/tokenCreate a token
POST/oauth2/registerCreate a register
GET/oauth2/register/{clientId}Get one register
PUT/oauth2/register/{clientId}Replace one register
DELETE/oauth2/register/{clientId}Delete one register
POST/oauth2/revokeImplements RFC 7009 token revocation. Revoking a refresh or access token ends the Sandscale session it belongs to. Unknown tokens still return 200.
POST/oauth2/tokenCreate a token
GET/oauth2/userinfoReturns the claims of the user an access token was issued to (OIDC Core 5.3). The token must be live, exactly as the authentication middleware requires: a revoked or expired session, a revoked token, a suspended user and an agent or device token are all refused with 401 invalid_token.
POST/oauth2/userinfoReturns the claims of the user an access token was issued to (OIDC Core 5.3). The token must be live, exactly as the authentication middleware requires: a revoked or expired session, a revoked token, a suspended user and an agent or device token are all refused with 401 invalid_token.

Endpoints

GET /.well-known/jwks.json

Serves the published signing keys (the active, next and retiring keys) with the keyset's cache lifetime: a next key is published at least twice that long before it signs, so a relying party that honours the header always holds the key of any ID token it is shown.

Permission
none
Response
200: object of any
Errors
503: jwks_unavailable

GET /.well-known/oauth-authorization-server

Serves the OAuth 2.0 authorization server metadata (RFC 8414): the OpenID discovery document with the grants and client authentication methods the token endpoint accepts. MCP clients read it after the sandbox MCP server's protected resource metadata names this server.

Permission
none
Response
200: object of any

GET /.well-known/openid-configuration

Serves the OpenID Provider metadata. On an Organization's sign-in host the issuer and every endpoint are that host's, so a relying party configured with that issuer validates the document.

Permission
none
Response
200: Discovery

GET /api/v1/applications

List applications

Permission
applications:read
Query parameters
audience, page_token
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized

POST /api/v1/applications

Create an application

Permission
applications:create
Request body
ApplicationInput
Response
201: CreatedApplication
Errors
400: invalid_json; 401: unauthorized; 402: entry_not_enabled; 403: forbidden, person_required; 415: content_type; 503: entitlement_unavailable, unavailable

GET /api/v1/applications/{clientId}

Get one application

Permission
applications:read
Path parameters
clientId
Response
200: Application
Errors
401: unauthorized

PATCH /api/v1/applications/{clientId}

Update one application

Permission
applications:update
Path parameters
clientId
Request body
ApplicationInput
Response
200: Application
Errors
400: invalid_json, invalid_request; 401: unauthorized; 415: content_type; 503: step_up_unavailable

DELETE /api/v1/applications/{clientId}

Delete one application

Permission
applications:delete
Path parameters
clientId
Errors
401: unauthorized

GET /api/v1/applications/{clientId}/{view}

One API (clientId "apis"), an application's logs or its grants.

Permission
applications:read
Path parameters
clientId, view
Query parameters
from, page_token, to
Response
200: API; 200: object of any
Errors
400: invalid_page_token, invalid_request; 401: unauthorized; 403: forbidden; 404: not_found; 503: audit_unavailable, unavailable

PUT /api/v1/applications/{clientId}/apis/{apiId}

Replace one api

Permission
applications.apis:manage
Path parameters
clientId, apiId
Request body
object
Response
200: APIGrant
Errors
400: invalid_json; 401: unauthorized; 415: content_type; 503: step_up_unavailable

DELETE /api/v1/applications/{clientId}/apis/{apiId}

Delete one api

Permission
applications.apis:manage
Path parameters
clientId, apiId
Errors
401: unauthorized

POST /api/v1/applications/{clientId}/secret/rotate

Create a rotate

Permission
applications:rotatesecret
Path parameters
clientId
Response
200: RotatedSecret
Errors
401: unauthorized

GET /api/v1/applications/apis

List apis

Permission
applications.apis:read
Query parameters
page_token
Response
200: object of any
Errors
400: invalid_request; 401: unauthorized

POST /api/v1/applications/apis

Create an api

Permission
applications.apis:manage
Request body
APIInput
Response
201: API
Errors
400: invalid_json; 401: unauthorized; 415: content_type

PATCH /api/v1/applications/apis/{apiId}

Update one api

Permission
applications.apis:manage
Path parameters
apiId
Request body
APIInput
Response
200: API
Errors
400: invalid_json; 401: unauthorized; 415: content_type

DELETE /api/v1/applications/apis/{apiId}

Delete one api

Permission
applications.apis:manage
Path parameters
apiId
Errors
401: unauthorized

POST /api/v1/auth/login

Create a login

Permission
none
Request body
loginRequest
Response
200: object of any
Errors
400: invalid_json, invalid_request; 401: invalid_credentials, invalid_mfa, mfa_required; 403: organization_access_denied, risk_denied; 415: content_type; 429: step_up_rate_limited; 503: step_up_unavailable

POST /api/v1/auth/login/step-up

Create a step up

Permission
none
Response
200: object of any
Errors
401: invalid_code, invalid_credentials, invalid_mfa, mfa_required, step_up_expired; 403: organization_access_denied; 503: step_up_unavailable

POST /api/v1/auth/login/step-up/resend

Create a resend

Permission
none
Response
202: object of any
Errors
401: step_up_expired, step_up_locked; 429: resend_too_soon, step_up_rate_limited; 503: step_up_unavailable

POST /api/v1/auth/logout

Create a logout

Permission
signed in
Response
200: object of string
Errors
401: unauthorized; 503: temporarily_unavailable

POST /api/v1/auth/passkeys/authenticate/begin

Create a begin

Permission
none
Request body
passkeyBeginRequest
Response
200: AuthenticationOptions
Errors
400: invalid_json, validation_error; 401: invalid_credentials; 415: content_type

POST /api/v1/auth/passkeys/authenticate/complete

Create a complete

Permission
none
Request body
passkeyCompleteRequest
Response
200: object of any
Errors
400: invalid_json, invalid_request; 401: invalid_credentials, invalid_mfa, mfa_required, user_verification_required; 403: organization_access_denied, risk_denied; 415: content_type; 503: step_up_unavailable

POST /api/v1/auth/password/change

Create a change

Permission
signed in
Request body
object
Errors
400: invalid_json, validation_error; 401: unauthorized; 403: invalid_credentials; 415: content_type; 503: temporarily_unavailable

POST /api/v1/auth/password/validate

Create a validate

Permission
none
Request body
validatePasswordRequest
Response
200: object of any
Errors
400: invalid_json; 415: content_type

POST /api/v1/auth/recovery-code/verify

Create a verify

Permission
signed in
Request body
verifyRecoveryCodeRequest
Response
200: object of any
Errors
400: invalid_json, invalid_request; 401: invalid_code, invalid_mfa, mfa_required, unauthorized; 403: forbidden, invalid_credentials; 415: content_type; 429: rate_limited; 503: temporarily_unavailable

POST /api/v1/auth/sessions/revoke

Create a revoke

Permission
signed in
Request body
revokeSessionRequest
Errors
400: invalid_json, invalid_request; 401: unauthorized; 404: not_found; 415: content_type; 503: temporarily_unavailable

POST /api/v1/auth/sessions/revoke-all

Create a revoke all

Permission
signed in
Errors
401: unauthorized; 500: server_error

POST /api/v1/auth/token/introspect

Implements RFC 7662 token introspection. The caller must authenticate as a confidential OAuth client (client_secret_basic, or client_id and client_secret in the form). Agent tokens and delegated tokens are reported active only to a resource server of their organization, with their effective scope, aud, act, org_id, token_use and consent_id.

Permission
none
Request body
introspectRequest
Response
200: IntrospectionResponse; 200: TokenIntrospection
Errors
400: invalid_json, invalid_request; 401: invalid_client; 415: content_type; 503: temporarily_unavailable

POST /api/v1/auth/token/refresh

Create a refresh

Permission
none
Request body
refreshRequest
Response
200: object of any
Errors
400: invalid_json, invalid_request; 401: invalid_grant, refresh_token_race, token_reuse_detected; 415: content_type; 503: temporarily_unavailable

POST /api/v1/auth/token/revoke

Create a revoke

Permission
none
Query parameters
token, token_type_hint
Request body
revokeRequest
Errors
400: invalid_json, invalid_request; 415: content_type; 503: temporarily_unavailable

POST /api/v1/oauth2/authorization-details

Create an authorization detail

Permission
oauth2:manage
Request body
CreateRARInput
Response
201: value
Errors
400: invalid_json, invalid_request; 401: unauthorized; 404: not_found; 415: content_type

GET /api/v1/oauth2/authorization-details/{clientId}

Get one authorization detail

Permission
api:access
Path parameters
clientId
Response
200: object of any
Errors
401: unauthorized; 404: not_found

DELETE /api/v1/oauth2/authorization-details/{id}

Delete one authorization detail

Permission
oauth2:manage
Path parameters
id
Errors
401: unauthorized; 404: not_found

GET /api/v1/oauth2/clients

List clients

Permission
api:access
Query parameters
limit, offset
Response
200: object of any
Errors
401: unauthorized

GET /oauth2/authorize

List authorize

Permission
none
Query parameters
acr_values, client_id, code_challenge, code_challenge_method, connection, intent, login_hint, max_age, nonce, organization, principal, prompt, redirect_uri, restarted, scope, state

POST /oauth2/authorize

Create an authorize

Permission
none
Query parameters
account_id, acr_values, client_id, code, code_challenge, code_challenge_method, csrf_token, decision, email, intent, max_age, method, nonce, organization, password, principal, prompt, recovery_code, redirect_uri, saved, scope, state, step, ticket
Errors
400: code; 401: code; 403: mfa_not_enrolled; 503: step_up_unavailable

POST /oauth2/device

Create a device

Permission
none
Response
200: object of any
Errors
400: client_retired, invalid_request, unauthorized_client; 401: invalid_client; 500: server_error

POST /oauth2/device/authorize

Create an authorize

Permission
none
Response
200: object of any
Errors
400: client_retired, invalid_request, unauthorized_client; 401: invalid_client; 500: server_error

POST /oauth2/device/token

Create a token

Permission
none
Response
200: TokenResponse
Errors
400: access_denied, authorization_pending, expired_token, invalid_grant, invalid_request, slow_down

POST /oauth2/register

Create a register

Permission
none
Request body
RegisterInput
Response
201: object of any
Errors
400: invalid_client_metadata, invalid_json; 401: invalid_token; 403: insufficient_scope; 415: content_type; 503: entitlement_unavailable

GET /oauth2/register/{clientId}

Get one register

Permission
none
Path parameters
clientId
Response
200: RegisteredClient
Errors
401: invalid_token; 403: invalid_token; 404: invalid_client

PUT /oauth2/register/{clientId}

Replace one register

Permission
none
Path parameters
clientId
Request body
RegisterInput
Response
200: RegisteredClient
Errors
400: invalid_client_metadata, invalid_json; 401: invalid_token; 403: invalid_token; 415: content_type

DELETE /oauth2/register/{clientId}

Delete one register

Permission
none
Path parameters
clientId
Errors
401: invalid_token; 403: invalid_token; 404: invalid_client

POST /oauth2/revoke

Implements RFC 7009 token revocation. Revoking a refresh or access token ends the Sandscale session it belongs to. Unknown tokens still return 200.

Permission
none
Query parameters
client_id, client_secret, token, token_type_hint

POST /oauth2/token

Create a token

Permission
none
Query parameters
client_id, client_secret, code, code_verifier, device_code, grant_type, organization, redirect_uri, refresh_token, scope
Response
200: TokenResponse
Errors
400: access_denied, authorization_pending, expired_token, invalid_grant, slow_down

GET /oauth2/userinfo

Returns the claims of the user an access token was issued to (OIDC Core 5.3). The token must be live, exactly as the authentication middleware requires: a revoked or expired session, a revoked token, a suspended user and an agent or device token are all refused with 401 invalid_token.

Permission
signed in
Response
200: UserInfo
Errors
401: invalid_token

POST /oauth2/userinfo

Returns the claims of the user an access token was issued to (OIDC Core 5.3). The token must be live, exactly as the authentication middleware requires: a revoked or expired session, a revoked token, a suspended user and an agent or device token are all refused with 401 invalid_token.

Permission
signed in
Response
200: UserInfo
Errors
401: invalid_token

Objects

object

FieldTypeDescription
current_passwordstring
new_passwordstring

object

FieldTypeDescription
scopesarray of string

ActorClaim

ActorClaim represents the actor in a delegated token (RFC 8693 §4.1).

FieldTypeDescription
substring

TokenIntrospection

The RFC 7662 answer for an agent token or a delegated token (POST /api/v1/auth/token/introspect). An inactive token has only Active false.

FieldTypeDescription
activeboolean
scope optionalstringThe token's effective scopes: those the agent, and for a person's delegation the person's consent, still cover.
token_type optionalstring
exp optionalinteger
iat optionalinteger
nbf optionalinteger
sub optionalstring
aud optionalstringThe token's audience: a resource server accepts only a token whose aud is its own.
iss optionalstring
jti optionalstring
act optionalActorClaimAct names the agent acting for the person of a delegated token.
org_id optionalstringThe organization of the token's agent.
token_use optionalstringTokenUseAgent or TokenUseDelegated.
consent_id optionalstringThe consent a person's delegation was issued under.

IntrospectionResponse

IntrospectionResponse implements RFC 7662 Token Introspection.

FieldTypeDescription
activeboolean
scope optionalstring
client_id optionalstring
username optionalstring
token_type optionalstring
exp optionalinteger
iat optionalinteger
nbf optionalinteger
sub optionalstring
aud optionalstring
iss optionalstring
jti optionalstring
mac optionalMACClaimThe person's clearances under mandatory access control, set only on the service node introspection of Base's Key Service: it narrows what Base's own compartment grants allow, never widens it.

MACClaim

A person's clearances as Base's Key Service receives them (version 2). Base admits a Base compartment B iff B is not in Governed, or some single clearance has a rank of at least Governed[B].Rank and compartments that include all of Governed[B].Compartments. Clearances are never joined: each is one clearance that applies to the person (their own or a group's).

FieldTypeDescription
versioninteger
clearancesarray of MACClearance
governedobject of MACGovernance
revision optionalstring

MACClearance

One unexpired clearance that applies to the person: its level, the level's rank in the organization's scheme (0 is the lowest), its MAC compartment keys and the Base compartments those compartments map to.

FieldTypeDescription
classificationstring
rankinteger
compartmentsarray of string
base_compartmentsarray of string

MACGovernance

The minimum label a single clearance must dominate to receive a lease for a Base compartment the scheme maps: a level (with its rank) and MAC compartment keys.

FieldTypeDescription
classificationstring
rankinteger
compartmentsarray of string

API

A registered API.

FieldTypeDescription
idstring
identifierstring
namestring
descriptionstring
scopesarray of APIScope
access_token_ttl_seconds optionalinteger
created_attimestamp
updated_attimestamp

APIGrant

An application's grant to an API.

FieldTypeDescription
api_idstring
identifierstring
namestring
scopesarray of string

APIInput

FieldTypeDescription
identifier optionalstring
name optionalstring
description optionalstring
scopes optionalarray of APIScope
access_token_ttl_secondsOptionalInt

APIScope

One scope of an API.

FieldTypeDescription
valuestring
descriptionstring

Application

The Applications API's view of a client.

FieldTypeDescription
client_idstring
namestring
descriptionstring
typestring
confidentialboolean
redirect_urisarray of string
logout_urisarray of string
allowed_originsarray of string
grant_typesarray of string
token_endpoint_auth_methodstring
require_pkceboolean
access_token_ttl_seconds optionalinteger
refresh_token_ttl_seconds optionalinteger
logo_uristring
assignment_requiredboolean
dynamically_registeredboolean
created_attimestamp
updated_attimestamp
secret_rotated_at optionaltimestamp
revisioninteger
audiencestringWho signs in to the application, chosen at creation and never changed: AudienceWorkforce (Sandscale people) or AudienceCustomers (end users of an Entry tenant).
entry_tenant_id optionalstringThe Entry tenant that holds a customers application; null for workforce.
external_id optionalstringThe Entry application id of a customers application once Entry binds it.

ApplicationInput

FieldTypeDescription
name optionalstring
type optionalstring
description optionalstring
redirect_uris optionalarray of string
logout_uris optionalarray of string
allowed_origins optionalarray of string
grant_types optionalarray of string
access_token_ttl_secondsOptionalInt
refresh_token_ttl_secondsOptionalInt
logo_uri optionalstring
audience optionalstringAudience (create only) is workforce (the default) or customers; it never changes.
entry_tenant_id optionalstringEntryTenantID (create only, required for customers) is the Entry tenant that holds the application; it never changes.

CreateRARInput

The input for creating an authorization detail

FieldTypeDescription
client_idstring
user_idstring
org_idstring
typestring
actionsarray of string
locationsarray of string
datatypesarray of string
identifierstring
privilegesarray of string
detailsJSON
expires_in optionalinteger object

CreatedApplication

Create's result: the secret only for a confidential type, shown once.

FieldTypeDescription
applicationApplication
client_secret optionalstring

OptionalInt

A JSON number that tells absent (Set false), null (Set, Null) and a value apart.

FieldTypeDescription
Setboolean
Nullboolean
Valueinteger

RegisterInput

FieldTypeDescription
client_namestring
client_uristring
logo_uristring
redirect_urisarray of string
grant_typesarray of string
response_typesarray of string
scopestring
token_endpoint_auth_methodstring
application_typestring
contactsarray of string
tos_uristring
policy_uristring
jwks_uristring
software_idstring
software_versionstring
org_idstring

RegisteredClient

FieldTypeDescription
idstring
client_idstring
client_namestring
client_uri optionalstring
logo_uri optionalstring
redirect_urisarray of string
grant_typesarray of string
response_typesarray of string
scopestring
token_endpoint_auth_methodstring
contacts optionalarray of string
tos_uri optionalstring
policy_uri optionalstring
jwks_uri optionalstring
software_id optionalstring
software_version optionalstring
org_id optionalstring
registration_client_uri optionalstring
client_id_issued_attimestamp
updated_attimestamp

RotatedSecret

RotateSecret's result, shown once.

FieldTypeDescription
client_secretstring
secret_rotated_attimestamp

TokenResponse

FieldTypeDescription
access_tokenstring
token_typestring
expires_in optionalinteger
refresh_token optionalstring
scope optionalstring
id_token optionalstring
issued_token_type optionalstring
principal_type optionalstring"root" for a root user session and empty otherwise; AuthTime (Unix seconds) and AccountID come with it, so the console renders the session from Sandscale's answer instead of reading the token.
auth_time optionalinteger
account_id optionalstring
organization_id optionalstringThe organization of the new session of an organization selection; empty for every other grant.

Discovery

FieldTypeDescription
issuerstring
authorization_endpointstring
token_endpointstring
userinfo_endpointstring
jwks_uristring
response_types_supportedarray of string
subject_types_supportedarray of string
id_token_signing_alg_values_supportedarray of string
scopes_supportedarray of string
claims_supportedarray of string
code_challenge_methods_supportedarray of string
device_authorization_endpointstringWhere an app that cannot open a browser starts the device authorization grant.
grant_types_supportedarray of string
authorization_response_iss_parameter_supportedbooleanAuthorizationResponseIssParameterSupported says every authorization response carries the issuer in the iss parameter (RFC 9207), so a client can detect a mix-up attack.
acr_values_supportedarray of stringThe acr values ID tokens carry and acr_values may request.
prompt_values_supportedarray of stringThe prompt values the authorization endpoint honours.

UserInfo

FieldTypeDescription
substring
name optionalstring
email optionalstring
email_verified optionalboolean
org_id optionalstring

AuthenticationOptions

FieldTypeDescription
challengestring
timeoutinteger
rpIdstring
userVerificationstring
allowCredentials optionalarray of CredentialDescriptor

CredentialDescriptor

FieldTypeDescription
typestring
idstring
transports optionalarray of string

introspectRequest

FieldTypeDescription
tokenstring
token_type_hintstring
client_idstring
client_secretstring

loginRequest

FieldTypeDescription
emailstring
passwordstring
organization_idstring
totpstring
recovery_codestring
remember_meboolean
device_tokenstringThe remembered-device token a previous step-up returned (device_token).

passkeyBeginRequest

FieldTypeDescription
emailstring
organization_idstring

passkeyCompleteRequest

FieldTypeDescription
responseJSON
totpstring
recovery_codestring

refreshRequest

FieldTypeDescription
refresh_tokenstring

revokeRequest

FieldTypeDescription
tokenstring
token_type_hintstring

revokeSessionRequest

FieldTypeDescription
session_idstring

validatePasswordRequest

FieldTypeDescription
passwordstring
organization_idstring

verifyRecoveryCodeRequest

FieldTypeDescription
user_idstring
codestring

This page is generated from the server's route table and the Go handlers that serve each route. Do not edit it by hand.