API reference

Preview, not available yet

This reference describes the v1 preview (contract version 1.0.0-preview.2). The API is switched off in every environment until Simblia announces it in the changelog. Breaking changes can still happen.

Generated from the OpenAPI 3.1.0 contract, version 1.0.0-preview.2. Download the contract (YAML) to generate a client or import it into your API tool.

Servers

Environment	Base URL
Production	https://api.simblia.com/v1
Sandbox (synthetic data, separate credentials; DEC-INT-013)	https://api-dev.simblia.com/v1

Authentication and scopes

clientBasic — HTTP basic. Client ID as user name, client secret as password. Only for the token endpoint.

clientCredentials — OAuth 2.0 client credentials, token URL https://api.simblia.com/v1/oauth/token.

Scope	Gives access to
organization.read	Read your organization’s name, type, institution type and country.

Operations

Operation	Summary	Access
POST /v1/oauth/token	Get an access token (client credentials)	HTTP Basic with your client ID and secret.
GET /.well-known/oauth-authorization-server	Authorization server metadata (RFC 8414)	None (public).
GET /v1/organization	Get your organization	Bearer access token with scope organization.read.

Get an access token (client credentials)

POST /v1/oauth/token

Full URLs: https://api.simblia.com/v1/oauth/token (Production), https://api-dev.simblia.com/v1/oauth/token (Sandbox (synthetic data, separate credentials; DEC-INT-013)).

OAuth 2.0 client credentials grant (RFC 6749 section 4.4). Send the client ID and secret with HTTP Basic authentication. Tokens last at most 15 minutes; there are no refresh tokens. Ask for a new token when the old one expires (INT-019).

Authentication: HTTP Basic with your client ID and secret.

Request body (application/x-www-form-urlencoded, required)

Property	Type	Required	Notes
grant_type	string; always client_credentials	yes
scope	string	no	Space-separated scopes. Must be a subset of the client’s scopes; defaults to all of them. Example: organization.read.

No other properties are sent or accepted.

Responses

Status	Description	Headers	Body
200	Access token issued.	Cache-Control: no-store	TokenResponse
400	OAuth error (RFC 6749 section 5.2), e.g. invalid_scope or unsupported_grant_type.	—	OAuthError
401	invalid_client. Wrong ID or secret, or the client is suspended or revoked.	—	OAuthError
429	rate_limited. More than 600 requests per minute for this client (DEC-INT-011).	Retry-After	Error

Authorization server metadata (RFC 8414)

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

Full URLs: https://api.simblia.com/.well-known/oauth-authorization-server (Production), https://api-dev.simblia.com/.well-known/oauth-authorization-server (Sandbox).

Lets OAuth libraries discover the token endpoint and supported options. Served at the host root, outside /v1.

Authentication: None (public).

Parameters: none.

Responses

Status	Description	Headers	Body
200	The metadata document.	—	AuthorizationServerMetadata

Get your organization

GET /v1/organization

Full URLs: https://api.simblia.com/v1/organization (Production), https://api-dev.simblia.com/v1/organization (Sandbox (synthetic data, separate credentials; DEC-INT-013)).

Authentication: Bearer access token with scope organization.read.

Parameters: none. Unknown query parameters are rejected with 422 validation_failed.

Responses

Status	Description	Headers	Body
200	The client’s organization.	Simblia-API-Status: preview	Organization
401	Missing, invalid or expired access token, a token from another environment, or a revoked client.	WWW-Authenticate	Error
403	The token lacks the scope this operation needs.	—	Error
422	validation_failed, e.g. an unknown query parameter.	—	Error
429	rate_limited. More than 600 requests per minute for this client (DEC-INT-011).	Retry-After	Error

Schemas

TokenResponse

Property	Type	Required	Notes
access_token	string	yes
token_type	string; always Bearer	yes
expires_in	integer; maximum 900	yes
scope	string	yes	Example: organization.read.

No other properties are sent or accepted.

OAuthError

Property	Type	Required	Notes
error	string; one of invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope	yes
error_description	string	no

Error

Property	Type	Required	Notes
code	string; one of unauthenticated, forbidden, validation_failed, rate_limited, dependency_unavailable	yes
correlation_id	string (uuid)	yes
retryable	boolean	yes
field_errors	array of object	yes

No other properties are sent or accepted.

Each item in field_errors:

Property	Type	Required	Notes
field	string	yes	Query parameter name.
code	string; one of invalid_value, not_allowed	yes

No other properties are sent or accepted.

AuthorizationServerMetadata

Property	Type	Required	Notes
issuer	string (uri)	yes	Example: https://api.simblia.com.
token_endpoint	string (uri)	yes	Example: https://api.simblia.com/v1/oauth/token.
grant_types_supported	array (each item: string; always client_credentials)	yes
token_endpoint_auth_methods_supported	array (each item: string; always client_secret_basic)	yes
scopes_supported	array of string	yes	Example: ["organization.read"].
response_types_supported	array of string; always empty	no
service_documentation	string (uri)	no

Organization

Property	Type	Required	Notes
organization_id	string (uuid)	yes
name	string	yes
type	string; always education	yes
institution_type	string; one of primary, secondary, higher, adult, other	yes
country	string	yes	ISO 3166-1 alpha-2. Example: DK.

No other properties are sent or accepted.

Error codes

Resource operations answer errors with the Error envelope:

HTTP	code	Meaning
401	unauthenticated	Missing, invalid or expired token, a token from another environment, or a suspended or revoked client. Sent with WWW-Authenticate: Bearer error="invalid_token".
403	forbidden	The token lacks the scope this operation needs (insufficient_scope).
422	validation_failed	A query parameter is unknown or invalid; see field_errors.
429	rate_limited	More than 600 requests per minute for this client. Wait the number of seconds in Retry-After.
503	dependency_unavailable	Temporary problem on our side. Retry with backoff.

The token endpoint answers with the standard OAuth 2.0 OAuthError format (RFC 6749 section 5.2). Possible error values: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope.