API Documentation
API Endpoint
https://id.skalio.netSkalio ID API Version 2 ¶
Welcome to the Skalio ID API, offering access to the Skalio ID project service. This document describes version 2 of the API.
Changelog ¶
Version 1 has been deprecated on 2022-12-07. It will remain available until further notice. Backwards compatibility will be attempted where possible, however this may result in a reduced information. Switching client applications to the v2 branch is highly recommended.
Major changes between v1 and v2:
-
Introduction of access tokens: most requests are authenticated by access tokens, which can be obtained by providing valid ID token.
-
Datastructure for
organizationhas been split:- Fetching information about an organization from the public resource returns reduced information. In particular,
subscriptioninformation is removed here. The same applies when navigating the profile of a person: the membership in anorganizationcontains only limited information about it. - Accessing information via the authenticated organization resource provides full information, including
subscriptionsand theorganizationProfile. - An organization can manage its avatar. Organization avatars are available via the public avatar resource.
- The
descriptionof an organization has been removed due to lack of requirements.
- Fetching information about an organization from the public resource returns reduced information. In particular,
Getting Started ¶
Transport ¶
The Spaces API is available via HTTPS only.
SSL 2.0 and SSL 3.0 are disabled.
The base URI for all resources is:
https://{hostname}/id/v2
Authorization ¶
Most requests require an authorization token in order to function properly. See authentication and authorization for details.
Auth tokens follow the JSON Web Token format. To obtain an ID token, either provide valid credentials, complete the multi-factor authentication process, or provide your federated identity through Open ID connect.
An ID token is long lived. During its validity, it can be used to obtain short lived access tokens from this or other backend services. Access tokens are used to authorize the interaction with the services. They are short lived and must be refreshed periodically.
Rate Limiting ¶
Many resources are protected against misuse or overload caused by badly behaving clients through rate limits according to the Leaky Bucket Algorithm as a Queue concept. Buckets are initially empty. Every request attempts to add a drop to the bucket. If the capacity does not allow this, the request is rejected (see ‘HTTP 509 Rate Limit Exceeded’ in section ‘Error handling’). Buckets drain over time, reducing their specific level and allowing new requests.
HTTP headers inform about the current bucket properties:
-
X-RateLimit-Limit
The total capacity of the current bucket.
Example:
X-RateLimit-Limit: 60 -
X-RateLimit-Remaining
The remaining capacity in the current bucket. Once this value is exhausted, future requests will be rejected until the bucket has been drained sufficiently.
Example:
X-RateLimit-Remaining: 42
Different resources use different buckets:
| Resource | Bucket Identifier | Capacity | Drainrate [1/s] |
|---|---|---|---|
| Login | Email-address of user | 3 | 1/15 |
| Environment | no limit | n/a | n/a |
API Deprecation ¶
Over time, the backend may change and a new version of the API will be released. To inform developers and clients of upcoming changes, the server indicates API deprecation by sending a Warning header with warning-code 229.
Example:
Warning: 299 - “API Deprecation Warning: Support for this request will be dropped soon, please update your client.”
While API deprecation is indicated, the API call will still function as documented. At a later stage, support for individual API calls up to the complete API-path may be dropped. This is indicated by responding with HTTP status code 410 (see section ‘Error handling’).
Payload format ¶
Unless explicitely stated, request and response bodies are encoded in JSON format. Appropriate headers (Content-Type: application/json, Accept: application/json) must be set.
Timestamps are encoded in ISO 8601 format, including timezone offset from UTC. Example:
{ “validDate”: “2037-12-31T15:29:59+00:00” }
Error handling ¶
The API responds with different HTTP Status Codes and messages:
-
HTTP 400 Bad Request
The request cannot be processed for syntax reasons. This could be because of a missing field, an incorrect type or an invalid value. The error message might provide more information. Check your code against the documentation. Retrying the request will not improve your chances of success.
Example:
{ "error": { "code": 400001, "message": "The request cannot be fulfilled.", "details": ["Invalid or unsupported value.", "Please consult the documentation."] } } -
HTTP 401 Not Authorized
Your request is missing an authenticated session ID, your session ID has expired, or your user is not valid. Obtain a new session and/or authenticate it (see the AuthResource).
-
HTTP 403 Forbidden
Your request was syntactically correct, but violated somehing else. Possible reasons are feature- and/or contract-limitations, accessing someone else’s data without authorization. Retrying the request will lead to the same result. The details of the message will provide more details.
Example:
{ "error": { "code": 403001, "message": "This request is forbidden.", "details": ["TTL is not acceptable"] } } -
HTTP 404 Not Found
The request could not be fulfilled, since the resource or entity at the URI does not exist (anymore). Retrying is futile.
-
HTTP 405 Method Not Allowed
The resource or entity does not support the HTTP method. Please consult the documentation.
-
HTTP 406 Not Acceptable
The backend cannot supply the response in the requested mediatype (as per the
Acceptrequest header). Please consult the documentation. You can retry your request, specifying appropriate headers. -
HTTP 409 Conflict
The request was not successful, because the a persistence-opertion failed. This can be temporary, or because another operation has modified the data in the meantime. Reread your data again, apply your changes and retry the request. You haven’t broken anything yet.
-
HTTP 410 Gone
The request was once valid but is no longer acceptable. This is a permanent situation. It indicates that parts of the API have since been deprecated and support for them has been dropped. It is recommended to consult the documentation and update clients.
-
HTTP 413 Request Entity Too Large
The backend is unwilling or unable to process a request body of this size.
-
HTTP 415 Unsupported Mediatype
The backend does not support the request payload, as announced in the
Content-Typeheader. -
HTTP 416 Range Not Satisfiable
This occurs when an upload or download request does not provide acceptable values for headers
RangeorContent-Range. -
HTTP 500 Server Error
Oops! It looks like something went horribly wrong in the backend. You might want to get in touch with us.
-
HTTP 503 Maintenance
The host you’re addressing is currently undergoing maintenance and is not serving requests. You can retry your request until is being accepted again.
-
HTTP 509 Rate Limit Exceeded
The request was not accepted because of a rate limit violation. The API is protected against overload and bruteforce attacks with rate limits. See the section on rate limiting for details. The response contains a
Retry-Afterheader (in seconds) to assist in retrying the request again.Example:
Retry-After: 23
Internationalization ¶
Message Bundles ¶
Request the message bundle in PO-file format.
Headers
Accept: text/x-gettext-translationHeaders
Content-Type: text/x-gettext-translationBody
msgstr ""
"Project-Id-Version: SkalioPush\n"
"Report-Msgid-Bugs-To: info@skalio.com\n"
"POT-Creation-Date: 2019-05-02 11:20+0200\n"
"PO-Revision-Date: \n"
"Last-Translator: Skalio GmbH <info@skalio.com>\n"
"Language-Team: Skalio GmbH <info@skalio.com>\n"
"Language: de_DE\n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"X-Generator: Poedit 1.7.4\n"
"Plural-Forms: nplurals=2; plural=(n != 1);\n"
#: src/main/java/com/skalio/skp/exceptions/BadRequest.java:18
msgid "The data cannot be parsed. Please send well-formed requests."
msgstr "Das Format der Daten ist nicht korrekt. Bitte versuchen Sie es erneut."
[...]The requested locale is not supported or does not exist.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Request the message bundle in JSON-encoded JED format.
Headers
Accept: application/jsonHeaders
Content-Type: application/jsonBody
{
"domain" : "messages",
"locale_data" : {
"messages" : {
"Folder quota exceeded." : [
"Verzeichnisvolumen überschritten."
],
"Please use only recipient groups that actually contain recipients." : [
"Bitte verwenden Sie nur Empfängergruppen, die auch Empfänger beinhalten."
],
"Maximum number of concurrent API requests reached." : [
"Maximale Anzahl gleichzeitiger API Requests erreicht."
],
[...]The requested locale is not supported or does not exist.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Get Message bundlesGET/id/v2/i18n/{locale}
Returns the message bundle in the requested locale.
- locale
Locales(required) Example: de_DERequested locale
Authentication ¶
Signup ¶
In order to use Skalio ID and other services that depend on it, a person can register by signing up to the service.
Headers
Content-Type: application/jsonBody
{
"address": "bob@example.test",
"password": "CorrectHorseBatteryStaple",
"name": "Bob",
"locale": "de_DE",
"timeZone": "Europe/Berlin"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"address": {
"type": "string",
"description": "Primary email address of the new person"
},
"password": {
"type": "string",
"description": "New password"
},
"name": {
"type": "string",
"description": "Optional name of the person"
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The preferred locale of the person"
},
"timeZone": {
"type": "string",
"description": "The person's timezone"
}
}
}Headers
Content-Type: application/jsonBody
{
"token": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The Base64 encoded and signed JWT"
}
}
}The email address is already in use.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}SignupPOST/id/v2/signup
Registers a new person. The returned ID token has a short validity and reduced functionality. To overcome this, the person must confirm the email address and then authenticate himself.
A new organization is created. The new person becomes a member of the admin-team of the new organization. The organization receives product entitlement for spaces.
OIDC ¶
In order to use services that depend on Skalio ID, a person can authenticate themselves using and external Identity provider based on the OpenID Connect and OAuth 2.0 concepts. This acts as an alternative to signing up for a Skalio ID account.
Multiple OAuth flows are supported.
Headers
Content-Type: application/jsonBody
{
"issuer": "https://skalio.com",
"jwksUrl": "https://id.skalio.net/id/v2/auth/keys",
"authUrl": "null",
"tokenUrl": "null",
"userinfoUrl": "null",
"revocationUrl": "null",
"responseTypes": "null",
"responseModes": "null",
"scopes": "null",
"grantTypes": "null"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"issuer": {
"type": "string",
"description": "Identifies the token issuer."
},
"jwksUrl": {
"type": "string",
"description": "URL where public keys can be retrieved."
},
"authUrl": {
"type": "string",
"description": "Future use."
},
"tokenUrl": {
"type": "string",
"description": "Future use."
},
"userinfoUrl": {
"type": "string",
"description": "Future use."
},
"revocationUrl": {
"type": "string",
"description": "Future use."
},
"responseTypes": {
"type": "string",
"description": "Future use."
},
"responseModes": {
"type": "string",
"description": "Future use."
},
"scopes": {
"type": "string",
"description": "Future use."
},
"grantTypes": {
"type": "string",
"description": "Future use."
}
},
"required": [
"issuer",
"jwksUrl"
]
}DiscoveryGET/id/v2/oidc/discovery
Returns the OpenID Connect discovery document. Applications and services integrating with Skalio ID for authentication purposes can query the backend for API endpoints regarding OpenID connect services.
This endpoint is ideally also available under the alias /.well-known/openid-configuration.
Full compliance with OpenID Connect is work in progress. Currently, the discovery document only provides the URL to the JSON Web Key Set.
Headers
Content-Type: application/jsonBody
{
"token": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The Base64 encoded and signed JWT"
}
}
}Headers
Content-Type: application/jsonBody
{
"token": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The Base64 encoded and signed JWT"
}
}
}The external token is not provided, invalid or is missing fields.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The email address described in the external token is not verified.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The email address is already in use.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Implicit flowPOST/id/v2/oidc/auth/implicit
Authenticates the person based on an ID token from an external OIDC identity provider. If necessary, a Skalio ID person is created referencing the subject of the external ID token. Finally, a Skalio ID token is issued and returned.
Headers
Content-Type: application/jsonBody
{
"code": "63ad6c5ac1614b5a",
"issuer": "https://example.net",
"clientId": "org.example.service.app.iOS",
"code_verifier `ab12cd34`": "Hello, world!"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "The authorization code as created by the external Identity provider."
},
"issuer": {
"type": "string",
"description": "The identifier of the extern identity provider."
},
"clientId": {
"type": "string",
"description": "The client ID that was used by the client when requesting the authorization code from the external identity provider."
},
"code_verifier `ab12cd34`": {
"type": "string",
"description": "A nonce that shall be used when requesting the token from the remote identity provider."
}
},
"required": [
"code",
"issuer",
"clientId"
]
}Headers
Content-Type: application/jsonBody
{
"token": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The Base64 encoded and signed JWT"
}
}
}The authorization code is not provided, invalid or missing fields.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The referenced ID provider cannot be found. Interacting with the external ID provider was not successful.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The email address is already in use.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Communication with the external ID provider failed. Please retry authentication.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authorization code flowPOST/id/v2/oidc/auth/code
Authenticates the person by exchanging an authorization code for the external ID token from the external OIDC provider. If necessary, a Skalio ID person is created referencing the subject of the external ID token. Finally, a Skalio ID token is issued and returned.
Headers
Content-Type: application/jsonBody
{
"redirectUrl": "https://host.example.net/callback"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"redirectUrl": {
"type": "string",
"description": "The requested URL to redirect the client after successful form-post flow."
}
},
"required": [
"redirectUrl"
]
}Headers
Content-Type: application/jsonBody
{
"state": "f9f53e7539dc",
"token": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"state": {
"type": "string",
"description": "The identifier for the incoming authentication flow."
},
"token": {
"type": "string",
"description": "The Base64 encoded and signed JWT."
}
},
"required": [
"state"
]
}The payload is not provided, invalid or missing fields.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Database error. Please retry authentication.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}PreflightPOST/id/v2/oidc/auth
This request must be used to announce incoming formpost requests beforehand. The backend creates and returns a new random value to be used as state in the subsequent form-post flow. The response also contains a short lived token referencing the state. This token can be used to pickup the actual Skalio ID token after completion of the formpost request by the external identity provider.
Headers
Content-Type: application/x-www-form-urlencodedBody
state=f9f53e7539dc&id_token=abc.123.def&user={...}&error=The authentication was successful.
Headers
location: https://host.example.net/static/callback/The authorization code is not provided, invalid or missing fields.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The referenced ID provider cannot be found. Interacting with the external ID provider was not successful.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Communication with the external ID provider failed. Please retry authentication.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Formpost flowPOST/id/v2/oidc/auth/form
Implements the endpoint where the external identity provider submits their ID token when authentication is executed via the formpost flow. If necessary, a Skalio ID person is created referencing the subject of the external ID token.
The client must have requested the creation of a state during the preflight request. This value must be used to initiate the form-post flow, and the external OIDC provider shall use it during its form-post here.
The response redirects the client to the URL that was registered during the preflight request. Possible error strings from the external identity provider will be appended to the redirect URL as query parameter error.
This resource is not intended to be used by clients. Instead, the external identity provider submits the ID token, and it is expected that the response is returned to the client.
Note: No Skalio ID token is created as part of this request. Instead, the client is expected to register the state in the preflight request and pickup the token afterwards.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"token": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The Base64 encoded and signed JWT"
}
}
}The token is missing, invalid or expired. The state has expired or does not exist.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The Skalio ID token referenced by the state has already been claimed before.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Pickup ID tokenGET/id/v2/oidc/auth
After completing the formpost flow, the client can use the token issued in the preflight request to fetch the Skalio ID token assigned to the state.
Note: the Skalio ID token matching the state can be picked up only once. Pickup must happen within 5 minutes of the incoming formpost, and with a valid pickup-token.
Authentication using Skalio ID ¶
Headers
Content-Type: application/jsonBody
{
"keys": [
{
"kid": "E7aBpD2f",
"kty": "EC",
"crv": "P-256",
"x": "DtteGBtczOtBHwgKe8AjWzH9AOcDBl-kohJ6yHDJLFQ=",
"y": "O5KV0_DeP7-MtZgVz9apsdJdWpg-GHMftTYLMIeRo6Q=",
"use": "sig"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"keys": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kid": {
"type": "string",
"enum": [
"E7aBpD2f"
],
"description": "Key identifier."
},
"kty": {
"type": "string",
"enum": [
"EC"
],
"description": "Type of key. One of `EC`, `RSA`."
},
"crv": {
"type": "string",
"enum": [
"P-256"
],
"description": "Describes the EC curve."
},
"x": {
"type": "string",
"enum": [
"DtteGBtczOtBHwgKe8AjWzH9AOcDBl-kohJ6yHDJLFQ="
],
"description": "Position on the EC curve."
},
"y": {
"type": "string",
"enum": [
"O5KV0_DeP7-MtZgVz9apsdJdWpg-GHMftTYLMIeRo6Q="
],
"description": "Position on the EC curve."
},
"use": {
"type": "string",
"enum": [
"sig"
],
"description": "Purpose of the key."
}
},
"required": [
"kid",
"kty",
"crv",
"x",
"y",
"use"
],
"additionalProperties": false
},
"description": "List of possible public keys."
}
},
"required": [
"keys"
]
}Get public signing keysGET/id/v2/auth/keys
Returns a JSON Web Key Set containing public keys that can be used to verify token signed by this service. The JWT header field kid references the matching public key.
Keys are rotated automatically. It is advised to fetch the JWKS regularly and not cache its contents.
Headers
Content-Type: application/jsonBody
{
"token": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The Base64 encoded and signed JWT"
}
}
}Get Delay-TokenGET/id/v1/auth/exists
This service is deprecated. For backwards compatibility, a static, fixed token is still being returned. However, this token is not required anymore.
Issues a delay token. This used to be required to authenticate the request to check whether an email address is in use.
Headers
Content-Type: application/jsonBody
{
"address": "bob@example.org"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"address": {
"type": "string",
"description": "Email address"
}
}
}The requested email address is in use by a Skalio ID person.
The payload is null or not valid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The requested email address is not known to Skalio ID.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}ExistsPOST/id/v2/auth/exists
Checks whether an email address exists within Skalio ID, i.e. is associated to a Skalio ID person.
Single-factor or first-factor authentication
Headers
Content-Type: application/jsonBody
{
"email": "alice@example.net",
"type": "bcrypt",
"key": "CorrectHorseBatteryStaple"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address of a person"
},
"type": {
"type": "string",
"enum": [
"bcrypt",
"totp",
"sms",
"u2f",
"recovery"
],
"description": "Type of authenticator"
},
"key": {
"type": "string",
"description": "Authentication data"
}
}
}Headers
Content-Type: application/jsonBody
{
"token": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The Base64 encoded and signed JWT"
}
}
}Invalid credentials are rejected
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Second-factor authentication
Headers
Content-Type: application/json
Authorization: Bearer ...mfa-token...Body
{
"email": "alice@example.net",
"type": "totp",
"key": "123456"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address of a person"
},
"type": {
"type": "string",
"description": "Type of authenticator"
},
"key": {
"type": "string",
"description": "Authentication data"
}
}
}Headers
Content-Type: application/jsonBody
{
"token": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The Base64 encoded and signed JWT"
}
}
}Mfa-token is missing or not valid. The authenticator is not supported or not verified.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Invalid credentials are rejected
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}LoginPOST/id/v2/auth/login
Authenticates a person based on given credentials (combination of identifier and authenticator).
If the person is using single-factor authentication or is completing multi-factor authentication, the response contains a JWT with scope idtoken. Such a token can be used to obtain an access token from this or other backend services.
Note: ID tokens must be kept safe and transmitted securely.
With multi-factor authentication enabled, the successful authentication using bcrypt results in a JWT with scope mfa. The authenticators claim describes available types of second-factor authenticators. This mfa-token must be provided in the authorization header when submitting the credentials containing the second factor.
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"tokens": [
{
"jti": "abc123",
"issuedTimestamp": "Hello, world!",
"expirationTimestamp": "Hello, world!",
"userAgent": "Hello, world!",
"ip": "Hello, world!"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"tokens": {
"type": "array",
"items": {
"type": "object",
"properties": {
"jti": {
"type": "string",
"enum": [
"abc123"
],
"description": "Unique reference and identifier of this token"
},
"issuedTimestamp": {
"type": "string",
"enum": [
""
],
"description": "Timestamp when the token was issued"
},
"expirationTimestamp": {
"type": "string",
"enum": [
""
],
"description": "Timestamp when the token will expire"
},
"userAgent": {
"type": "string",
"enum": [
""
],
"description": "The user agent of the client that requested the token"
},
"ip": {
"type": "string",
"enum": [
""
],
"description": "The public IP address of the client that requested the token"
}
},
"required": [
"jti",
"issuedTimestamp",
"expirationTimestamp",
"userAgent",
"ip"
],
"additionalProperties": false
},
"description": "List of tokens"
}
},
"required": [
"tokens"
]
}List tokensGET/id/v2/auth
Returns a list of unexpired ID tokens that have been issued for the person.
Requests must be authenticated with an ID token.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"token": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The Base64 encoded and signed JWT"
}
}
}New UID tokenPOST/id/v2/auth/uid
Creates a new uid token. The token has a long lifetime and is used to detect this person in otherwise unauthenticated requests.
A uid token cannot be revoked.
Requests must be authenticated with an ID token.
Headers
Authorization: Bearer abcdef.123456.ghijklThe upgrade was successful and a new token has been issued.
Headers
Content-Type: application/jsonBody
{
"token": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The Base64 encoded and signed JWT"
}
}
}The token does not have a valid authLevel.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The token is not valid or has expired.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The primay email address of the person is not yet verified, or the provided token cannot be upgraded.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Upgrade ID tokenPOST/id/v2/auth/upgrade
If applicable, this request exchanges an ID token with low authLevel for a new ID token with a higher authLevel.
Its purpose is to ensure a smooth transition from unverified to verified person during the signup process. After a person has verified his primary address, he may use this request to exchange his ID token without re-authentication.
The ID token used to authenticate this request is blacklisted.
Requests must be authenticated with an ID token.
Headers
Authorization: Bearer abcdef.123456.ghijklAn access token has been issued.
Headers
Content-Type: application/jsonBody
{
"token": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The Base64 encoded and signed JWT"
}
}
}The token is not valid or has expired.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Obtain access tokenPOST/id/v2/auth/access?cookie={cookie}
To interact with Skalio ID, a short lived access token is required.
Requests must be authenticated with an ID token.
- cookie
boolean(optional)If true, the access token will be issued as a cookie as well. Default: false.
Headers
Authorization: Bearer abcdef.123456.ghijklThe requested token belongs to someone else.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}LogoutPOST/id/v2/auth/logout?jti={jti}
Deauthenticates a person and blacklists the token against further use. If no token is specified, the token that authenticates this request is blacklisted (self-logout).
Specifying keyword all as value to parameter jti ensures that the authenticated person is logged out everywhere. In other words, this ends all sessions of the authenticated person, including the active session.
Requests must be authenticated with an ID token.
- jti
string(optional)optional transaction id of the token to be blacklisted. Use
allto end all sessions.
Headers
Content-Type: application/jsonBody
{
"address": "bob@example.org"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"address": {
"type": "string",
"description": "Email address"
}
}
}The requested email address does not exist or is not verified.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Password recoveryPOST/id/v2/auth/reset
Triggers the password recovery process. The person must provide an existing, verified email address.
Headers
Content-Type: application/jsonBody
{
"token": "abcdef.123456.ghijkl"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The Base64 encoded and signed JWT"
}
}
}Key not found, or has expired.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Password resetPOST/id/v2/auth/reset/{key}
Authenticates the person based on the password recovery key. If the key is valid and not yet expired, it returns an ID token with short validity, containing a setPassword claim. When exchanged for an access token, this claim is transferred.
An access token containing the setPassword claim allows changing the bcrypt authenticator (“password”) without having to provide the current password.
- key
string(required) Example: s0ga45as-4.sd9ya5The key as sent in the password recovery email.
Profile ¶
Profile Management ¶
The subject of all requests in this resource is always the authenticated principal. It is not possible to list or modify the data of another person through this resource.
The profile contains several timestamps:
-
createdAtis set at account creation, never updated -
lastLoginAtis set after every successful login
Requests must be authenticated with an access token.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"name": "Horst Groby",
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"uid": "533h18.ygguv_b_0",
"hasAvatar": true,
"fingerprint": [
{
"name": "christmasTree",
"codePoint": 127876,
"title": "christmas tree"
}
],
"createdAt": "2022-05-11T10:50:50Z",
"lastLoginAt": "2022-06-17T12:46:56Z",
"emails": [
{
"address": "bob@example.org",
"primary": true,
"verified": true,
"removeAt": "null"
}
],
"memberships": [
{
"organization": {
"uid": "n_gwumunrj77j-r0",
"name": "Example Inc",
"hasAvatar": true
},
"teams": [
{
"uid": "as9wfals-as.2.3",
"name": "Sales Department",
"description": "Hello, world!",
"privilege": "read"
}
]
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name"
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The preferred locale of the person"
},
"timeZone": {
"type": "string",
"description": "The person's timezone"
},
"uid": {
"type": "string",
"description": "Unique ID of the person"
},
"hasAvatar": {
"type": "boolean",
"description": "True if the person has an avatar."
},
"fingerprint": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"enum": [
"christmasTree"
],
"description": "The unique name of the emoji"
},
"codePoint": {
"type": "number",
"enum": [
127876
],
"description": "The emoji's codepoint in Unicode"
},
"title": {
"type": "string",
"enum": [
"christmas tree"
],
"description": "The english translation key"
}
},
"required": [
"name",
"codePoint",
"title"
],
"additionalProperties": false
},
"description": "The persons fingerprint"
},
"createdAt": {
"type": "string",
"description": "Timestamp when the person was created"
},
"lastLoginAt": {
"type": "string",
"description": "Timestamp when the person has last authenticated"
},
"emails": {
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"type": "string",
"enum": [
"bob@example.org"
],
"description": "Email address"
},
"primary": {
"type": "boolean",
"enum": [
true
],
"description": "The primary address will receive notifications. Readonly."
},
"verified": {
"type": "boolean",
"enum": [
true
],
"description": "True if the owner has proven control over it. Readonly."
},
"removeAt": {
"type": [
"string",
"null"
],
"enum": [
"null",
null
],
"description": "ISO 8601 timestamp when an unverified email address is being removed. Null if verified."
}
},
"required": [
"address",
"primary",
"verified",
"removeAt"
],
"additionalProperties": false
},
"description": "List of email addresses"
},
"memberships": {
"type": "array",
"items": {
"type": "object",
"properties": {
"organization": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"n_gwumunrj77j-r0"
],
"description": "Unique ID of the organization."
},
"name": {
"type": "string",
"enum": [
"Example Inc"
],
"description": "The name of the organization, if set."
},
"hasAvatar": {
"type": "boolean",
"enum": [
false
],
"description": "True if the organization has an avatar."
}
},
"required": [
"uid",
"hasAvatar"
],
"additionalProperties": false
},
"teams": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"as9wfals-as.2.3"
],
"description": "Unique ID of the team"
},
"name": {
"type": "string",
"enum": [
"Sales Department"
],
"description": "Name of the team"
},
"description": {
"type": "string",
"enum": [
""
],
"description": "Descriptive text"
},
"privilege": {
"type": "string",
"enum": [
"read",
"creator",
"admin"
],
"description": "Privilege the person has in this organization"
}
},
"required": [
"uid",
"name",
"privilege"
],
"additionalProperties": false
}
}
},
"required": [
"organization",
"teams"
],
"additionalProperties": false
},
"description": "List of organizations the person is a member of"
}
},
"required": [
"fingerprint",
"emails",
"memberships"
]
}Get ProfileGET/id/v2/profile
This returns the complete profile of the principal.
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklBody
{
"name": "Horst Groby",
"locale": "de_DE",
"timeZone": "Europe/Berlin"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name"
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The preferred locale of the person"
},
"timeZone": {
"type": "string",
"description": "The person's timezone"
}
}
}Headers
Content-Type: application/jsonBody
{
"name": "Horst Groby",
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"uid": "533h18.ygguv_b_0",
"hasAvatar": true,
"fingerprint": [
{
"name": "christmasTree",
"codePoint": 127876,
"title": "christmas tree"
}
],
"createdAt": "2022-05-11T10:50:50Z",
"lastLoginAt": "2022-06-17T12:46:56Z",
"emails": [
{
"address": "bob@example.org",
"primary": true,
"verified": true,
"removeAt": "null"
}
],
"memberships": [
{
"organization": {
"uid": "n_gwumunrj77j-r0",
"name": "Example Inc",
"hasAvatar": true
},
"teams": [
{
"uid": "as9wfals-as.2.3",
"name": "Sales Department",
"description": "Hello, world!",
"privilege": "read"
}
]
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name"
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The preferred locale of the person"
},
"timeZone": {
"type": "string",
"description": "The person's timezone"
},
"uid": {
"type": "string",
"description": "Unique ID of the person"
},
"hasAvatar": {
"type": "boolean",
"description": "True if the person has an avatar."
},
"fingerprint": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"enum": [
"christmasTree"
],
"description": "The unique name of the emoji"
},
"codePoint": {
"type": "number",
"enum": [
127876
],
"description": "The emoji's codepoint in Unicode"
},
"title": {
"type": "string",
"enum": [
"christmas tree"
],
"description": "The english translation key"
}
},
"required": [
"name",
"codePoint",
"title"
],
"additionalProperties": false
},
"description": "The persons fingerprint"
},
"createdAt": {
"type": "string",
"description": "Timestamp when the person was created"
},
"lastLoginAt": {
"type": "string",
"description": "Timestamp when the person has last authenticated"
},
"emails": {
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"type": "string",
"enum": [
"bob@example.org"
],
"description": "Email address"
},
"primary": {
"type": "boolean",
"enum": [
true
],
"description": "The primary address will receive notifications. Readonly."
},
"verified": {
"type": "boolean",
"enum": [
true
],
"description": "True if the owner has proven control over it. Readonly."
},
"removeAt": {
"type": [
"string",
"null"
],
"enum": [
"null",
null
],
"description": "ISO 8601 timestamp when an unverified email address is being removed. Null if verified."
}
},
"required": [
"address",
"primary",
"verified",
"removeAt"
],
"additionalProperties": false
},
"description": "List of email addresses"
},
"memberships": {
"type": "array",
"items": {
"type": "object",
"properties": {
"organization": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"n_gwumunrj77j-r0"
],
"description": "Unique ID of the organization."
},
"name": {
"type": "string",
"enum": [
"Example Inc"
],
"description": "The name of the organization, if set."
},
"hasAvatar": {
"type": "boolean",
"enum": [
false
],
"description": "True if the organization has an avatar."
}
},
"required": [
"uid",
"hasAvatar"
],
"additionalProperties": false
},
"teams": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"as9wfals-as.2.3"
],
"description": "Unique ID of the team"
},
"name": {
"type": "string",
"enum": [
"Sales Department"
],
"description": "Name of the team"
},
"description": {
"type": "string",
"enum": [
""
],
"description": "Descriptive text"
},
"privilege": {
"type": "string",
"enum": [
"read",
"creator",
"admin"
],
"description": "Privilege the person has in this organization"
}
},
"required": [
"uid",
"name",
"privilege"
],
"additionalProperties": false
}
}
},
"required": [
"organization",
"teams"
],
"additionalProperties": false
},
"description": "List of organizations the person is a member of"
}
},
"required": [
"fingerprint",
"emails",
"memberships"
]
}Update ProfilePUT/id/v2/profile
The principal can change only a select number of fields here. Others, such as email addresses need, to be changed via their respective resources.
Headers
Authorization: Bearer abcdef.123456.ghijklThe delete operation cannot be executed since its outcome would conflict with integrity constraints of the persons organization. The organization must be deleted first.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Account DeletionDELETE/id/v2/profile
Deletes the account permanently. Cascades to other applications.
Avatar Management ¶
A person can upload an image to represent his account in public. The avatar image can later be requested without authorization by querying the public avatar resource.
Requests must be authenticated with an access token.
Headers
Content-Type: image/jpg
Authorization: Bearer abcdef.123456.ghijklBody
{... payload ...}Headers
Content-Type: image/jpeg
Location: /id/v2/profile/avatarBody
{... payload ...}The image could not be processed.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Upload AvatarPUT/id/v2/profile/avatar
The resource accept payload with the following content types only:
-
image/jpeg -
image/png -
image/gif
An uploaded avatar is cropped to a square size, resized and re-encoded to JPG.
Updating an avatar triggers a SignalingEvent of type PROFILE_AVATAR_UPDATED into the feed of interested persons.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: image/jpeg
Etag: "213508"Body
{... payload ...}No avatar has been uploaded.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Get AvatarGET/id/v2/profile/avatar?height={height}
Return the persons avatar if one has been uploaded.
In addition to the Authorization header, this request alternatively accepts the valid access token in the form of a cookie with name acct. If both are present, the header will be evaluated only.
- height
number(optional) Example: 80the requested size of the avatar image
Headers
Authorization: Bearer abcdef.123456.ghijklDelete AvatarDELETE/id/v2/profile/avatar
Removes the persons avatar if one has been uploaded.
Deleting an avatar triggers a SignalingEvent of type PROFILE_AVATAR_UPDATED into the feed of interested persons.
Email Management ¶
A person can register any number of email addresses for his account. Before an email address can be used, it must be verified. Email verification confirms that the person has control over the claimed address.
At all times, exactly one verified email address of a person is marked as primary. A person will receive notifications on his primary email address only.
Managing email addresses requires a valid ID token. Request for or confirmation of a email verification message does not require authentication.
Requests must be authenticated with an access token.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"emails": [
{
"address": "bob@example.org",
"primary": true,
"verified": true,
"removeAt": "null"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"emails": {
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"type": "string",
"enum": [
"bob@example.org"
],
"description": "Email address"
},
"primary": {
"type": "boolean",
"enum": [
true
],
"description": "The primary address will receive notifications. Readonly."
},
"verified": {
"type": "boolean",
"enum": [
true
],
"description": "True if the owner has proven control over it. Readonly."
},
"removeAt": {
"type": [
"string",
"null"
],
"enum": [
"null",
null
],
"description": "ISO 8601 timestamp when an unverified email address is being removed. Null if verified."
}
},
"required": [
"address",
"primary",
"verified",
"removeAt"
],
"additionalProperties": false
}
}
},
"required": [
"emails"
]
}List addressesGET/id/v2/profile/emails
Lists all email addresses of the person.
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklBody
{
"address": "bob@example.org"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"address": {
"type": "string",
"description": "Email address"
}
}
}Headers
Content-Type: application/json
Location: /id/v2/profile/emails/{address}Body
{
"address": "bob@example.org",
"primary": true,
"verified": true,
"removeAt": "null"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"address": {
"type": "string",
"description": "Email address"
},
"primary": {
"type": "boolean",
"description": "The primary address will receive notifications. Readonly."
},
"verified": {
"type": "boolean",
"description": "True if the owner has proven control over it. Readonly."
},
"removeAt": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp when an unverified email address is being removed. Null if verified."
}
}
}The requested email address is not valid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The email address is already in use.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Register new AddressPOST/id/v2/profile/emails
Creates a new unverified, secondary email address for this person and triggers the verification process. Throws an error, if the requested email address is already in use anywhere.
Headers
Authorization: Bearer abcdef.123456.ghijklThe requested email address is marked as primary or belongs to someone else.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Delete Email AddressDELETE/id/v2/profile/emails/{address}
Removes the requested address. Throws an error, if the requested address is marked as primary or belongs to someone else.
- address
string(required) Example: bob@example.org
Headers
Authorization: Bearer abcdef.123456.ghijklThe requested email address is not yet verified or belongs to someone else.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The requested email address is not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Mark Address as PrimaryPOST/id/v2/profile/emails/{address}/primary
Marks the given address as the only primary address of all addresses of the person. Throws an error, if the address is not found, belongs to someone else or is not yet verified.
- address
string(required) Example: bob@example.org
The rate-limit for this request has been exceeded.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 429002,
"message": "Maximum number of concurrent API requests reached.",
"details": [
"Hello, world!",
"Please try again after waiting some time."
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Request Address VerificationPOST/id/v2/profile/emails/{address}/verify
Requests verification of the email address again. Renders all previously sent verification messages regarding this email invalid. Note: if the address has been verified already, this request is successful, but will not trigger a new verification message.
The resource is rate-limit-protected. Verification for an address can only be triggered once per minute.
- address
string(required) Example: bob@example.org
Headers
Content-Type: application/jsonThe email address has already been verified
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The requested confirmation key is not found or has expired.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Confirm Address VerificationPOST/id/v2/confirm/{key}
Completes the verification of an email address. This request does not require authentication!
- key
string(required) Example: bxno3kikie5js6hiConfirmation key from the verification message.
Authenticator management ¶
An authenticator is the means used to confirm the identity of a person. A person authenticates to a computer system or application by demonstrating that he or she has possession and control of an authenticator.
Multiple authenticators can be registered, depending on the type.
| Type | Description | Supported cardinality |
|---|---|---|
| bcrypt | Password | exactly 1 |
| totp | Timebased one-time key | 0 or 1 |
| sms | Timebased one-time key, delivered via SMS | 0 or 1 |
| u2f | Hardware token | 0 or more |
| recovery | Small number of one-time passcodes with unlimited expiration | 0 or 1 |
Authenticator types sms and u2f are not yet supported.
Requests must be authenticated with an access token.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"authenticators": [
{
"type": "bcrypt",
"name": "My password",
"uid": "a9v_fas8gl57l.3",
"registeredAt": "2020-05-26T07:31:57.298Z",
"updatedAt": "2020-05-26T07:31:57.298Z",
"verified": true,
"key": "null",
"dataUri": "null"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"authenticators": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"bcrypt",
"totp",
"sms",
"u2f",
"recovery"
],
"description": "The type of the authenticator"
},
"name": {
"type": "string",
"enum": [
"My password"
],
"description": "Personal description of the authenticator"
},
"uid": {
"type": "string",
"enum": [
"a9v_fas8gl57l.3"
],
"description": "Unique ID of the authenticator"
},
"registeredAt": {
"type": "string",
"enum": [
"2020-05-26T07:31:57.298Z"
],
"description": "Timestamp when the authenticator was created"
},
"updatedAt": {
"type": "string",
"enum": [
"2020-05-26T07:31:57.298Z"
],
"description": "Timestamp when the authenticator was last updated"
},
"verified": {
"type": "boolean",
"enum": [
true
],
"description": "True, if the authenticator has been verified"
},
"key": {
"type": "string",
"enum": [
"null"
],
"description": "This may include the key to a newly registered authenticator. Only shown once."
},
"dataUri": {
"type": "string",
"enum": [
"null"
],
"description": "This may include an image in data-URI format, representing the key of a newly registered authenticator."
}
},
"required": [
"type",
"uid",
"registeredAt",
"updatedAt",
"verified"
],
"additionalProperties": false
}
}
},
"required": [
"authenticators"
]
}Get registered authenticatorsGET/id/v2/profile/authenticators
Returns a list of all registered authenticators of the person.
Registers a new TOTP authenticator.
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklBody
{
"type": "totp",
"name": "Google Authenticator",
"pubKey": "null"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of the authenticator"
},
"name": {
"type": "string",
"description": "Personal description of the authenticator"
},
"pubKey": {
"type": "string",
"description": "The public key. Depending on the type, it may be required."
}
},
"required": [
"type"
]
}Returns the shared secret for the TOTP authenticator. A QrCode, encoded in data URI scheme, supports convenient onboarding of an authenticator app.
Headers
Content-Type: application/json
Location: https://id.skalio.net/id/v2/profile/authenticators/a9v_fas8gl57l.3Body
{
"type": "totp",
"name": "Google Authenticator",
"uid": "3gvvyykfl139hpde",
"registeredAt": "2020-05-26T07:31:57.298Z",
"updatedAt": "2020-05-26T07:31:57.298Z",
"verified": "false",
"key": "QS7KLSIFCPPG5KYTXT4ELYIBNWAPNIDS",
"dataUri": "data:image/png;base64,iVBORw0KG..."
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of the authenticator"
},
"name": {
"type": "string",
"description": "Personal description of the authenticator"
},
"uid": {
"type": "string",
"description": "Unique ID of the authenticator"
},
"registeredAt": {
"type": "string",
"description": "Timestamp when the authenticator was created"
},
"updatedAt": {
"type": "string",
"description": "Timestamp when the authenticator was last updated"
},
"verified": {
"type": "string",
"description": "True, if the authenticator has been verified"
},
"key": {
"type": "string",
"description": "This may include the key to a newly registered authenticator. Only shown once."
},
"dataUri": {
"type": "string",
"description": "This may include an image in data-URI format, representing the key of a newly registered authenticator."
}
},
"required": [
"type"
]
}A field is missing or a value is incorrect. The authenticator-type is not supported (yet).
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Credentials of this type cannot be registered any more. A federated identity is not allowed to register authenticators.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Registers a new or replaces the existing recovery authenticator.
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklBody
{
"type": "recovery",
"name": "Backup codes",
"pubKey": "null"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of the authenticator"
},
"name": {
"type": "string",
"description": "Personal description of the authenticator"
},
"pubKey": {
"type": "string",
"description": "The public key. Depending on the type, it may be required."
}
},
"required": [
"type"
]
}Returns the passcodes. Previously created passcodes are no longer valid.
Headers
Content-Type: application/json
Location: https://id.skalio.net/id/v2/profile/authenticators/a9v_fas8gl57l.3Body
{
"type": "recovery",
"name": "Backup codes",
"uid": "3gvvyykfl139hpde",
"registeredAt": "2020-05-26T07:31:57.298Z",
"updatedAt": "2020-05-26T07:31:57.298Z",
"verified": "true",
"key": "2zqtTtwCoqYw QExttcc6cycP orcFwD6CNaQe",
"dataUri": "null"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of the authenticator"
},
"name": {
"type": "string",
"description": "Personal description of the authenticator"
},
"uid": {
"type": "string",
"description": "Unique ID of the authenticator"
},
"registeredAt": {
"type": "string",
"description": "Timestamp when the authenticator was created"
},
"updatedAt": {
"type": "string",
"description": "Timestamp when the authenticator was last updated"
},
"verified": {
"type": "string",
"description": "True, if the authenticator has been verified"
},
"key": {
"type": "string",
"description": "This may include the key to a newly registered authenticator. Only shown once."
},
"dataUri": {
"type": "string",
"description": "This may include an image in data-URI format, representing the key of a newly registered authenticator."
}
},
"required": [
"type"
]
}A field is missing or a value is incorrect. The authenticator-type is not supported (yet).
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}A federated identity is not allowed to register authenticators.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Register new authenticatorPOST/id/v2/profile/authenticators
Registers new, additional authenticator.
Most authenticator types can be registered only once per person. Typically, they must be verified before they can be used.
The recovery authenticator can be re-registered, which replaces all existing passcodes. This authenticator also does not require verification. Once registered, the passcodes are ready to be used.
Depending on the type of authenticator, the shared secret is returned once in the key field. The user should persist the secret, since it cannot be retrieved afterwards. In some cases, an image is returned, encoded in data URI scheme, supporting the onboarding of an authenticator app.
-
totp: Authenticator seed secret is returned. QrCode is returned for easy setup of authenticator app. -
recovery: All valid passcodes are returned, separated by a whitespace character.
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklBody
{
"email": "alice@example.net",
"type": "totp",
"key": "123456"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address of a person"
},
"type": {
"type": "string",
"description": "Type of authenticator"
},
"key": {
"type": "string",
"description": "Authentication data"
}
}
}A field is missing or a value is incorrect. The authenticator-type is not supported (yet). The credentials-type does not match the authenticator-type.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Verification failed.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authenticator not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Verify registered authenticatorPOST/id/v2/profile/authenticators/{uid}/verify
Proves the person’s control over a newly registered authenticator by authenticating against it. If successful, this marks the authenticator as verified.
- uid
string(required) Example: '3gvvyykfl139hpde'The uid of the authenticator.
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"type": "bcrypt",
"name": "My password",
"uid": "a9v_fas8gl57l.3",
"registeredAt": "2020-05-26T07:31:57.298Z",
"updatedAt": "2020-05-26T07:31:57.298Z",
"verified": true,
"key": "null",
"dataUri": "null"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"bcrypt",
"totp",
"sms",
"u2f",
"recovery"
],
"description": "The type of the authenticator"
},
"name": {
"type": "string",
"description": "Personal description of the authenticator"
},
"uid": {
"type": "string",
"description": "Unique ID of the authenticator"
},
"registeredAt": {
"type": "string",
"description": "Timestamp when the authenticator was created"
},
"updatedAt": {
"type": "string",
"description": "Timestamp when the authenticator was last updated"
},
"verified": {
"type": "boolean",
"description": "True, if the authenticator has been verified"
},
"key": {
"type": "string",
"description": "This may include the key to a newly registered authenticator. Only shown once."
},
"dataUri": {
"type": "string",
"description": "This may include an image in data-URI format, representing the key of a newly registered authenticator."
}
},
"required": [
"type"
]
}Authenticator not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Fetch authenticatorGET/id/v2/profile/authenticators/{uid}
Returns the referenced authenticator.
- uid
string(required) Example: 'a9v_fas8gl57l.3'The uid of the authenticator.
Headers
Content-Type: application/json
Authorization: Bearer abcdef.123456.ghijklBody
{
"name": "My password",
"pubKey": "new password",
"authKey": "CorrectHorseBatteryStaple"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Personal description of the authenticator"
},
"pubKey": {
"type": "string",
"description": "The new public key, typically in plain text"
},
"authKey": {
"type": "string",
"description": "A key with which the update is authorized, typically in plain text"
}
}
}Headers
Content-Type: application/jsonBody
{
"type": "bcrypt",
"name": "My password",
"uid": "a9v_fas8gl57l.3",
"registeredAt": "2020-05-26T07:31:57.298Z",
"updatedAt": "2020-05-26T07:31:57.298Z",
"verified": true,
"key": "null",
"dataUri": "null"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"bcrypt",
"totp",
"sms",
"u2f",
"recovery"
],
"description": "The type of the authenticator"
},
"name": {
"type": "string",
"description": "Personal description of the authenticator"
},
"uid": {
"type": "string",
"description": "Unique ID of the authenticator"
},
"registeredAt": {
"type": "string",
"description": "Timestamp when the authenticator was created"
},
"updatedAt": {
"type": "string",
"description": "Timestamp when the authenticator was last updated"
},
"verified": {
"type": "boolean",
"description": "True, if the authenticator has been verified"
},
"key": {
"type": "string",
"description": "This may include the key to a newly registered authenticator. Only shown once."
},
"dataUri": {
"type": "string",
"description": "This may include an image in data-URI format, representing the key of a newly registered authenticator."
}
},
"required": [
"type"
]
}A field is missing or a value is incorrect. The authenticator-type is not supported (yet).
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authorization of the public-key change failed
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authenticator not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Update existing authenticatorPUT/id/v2/profile/authenticators/{uid}
Changes or updates the existing authenticator. The type cannot be changed.
Changing the public key is only allowed for type bcrypt and requires additional authorization. One of the following methods is acceptable:
-
The request contains an
authKey, which validates successfully against the previous public key. -
The authenticating access token contains
setPasswordclaim with valuetrue. This is the case after password recovery.
Changing the name only does not require additional authorization, and does not update field updatedAt.
- uid
string(required) Example: 'a9v_fas8gl57l.3'The uid of the authenticator.
Headers
Authorization: Bearer abcdef.123456.ghijklThe authenticator-type is not supported (yet).
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Credentials cannot be unregistered.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authenticator not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Unregister authenticatorDELETE/id/v2/profile/authenticators/{uid}
Removes authenticator, if their type allows for this.
- uid
string(required) Example: 'a8as9ykd_0s93'The uid of the authenticator.
Public ¶
Request public information ¶
It is possible for an authenticated person to retrieve public information about an entity.
Request are throttled. Caching and conditional GET requests are encouraged.
Requests must be authenticated with a UID token.
Headers
Content-Type: application/json
Etag: "a1b2c3"Body
{
"uid": "533h18.ygguv_b_0",
"name": "Horst Groby",
"email": "alice@example.net",
"hasAvatar": true,
"fingerprint": [
{
"name": "christmasTree",
"codePoint": 127876,
"title": "christmas tree"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique ID of the person"
},
"name": {
"type": "string",
"description": "Name"
},
"email": {
"type": "string",
"description": "Primary email address, if verified"
},
"hasAvatar": {
"type": "boolean",
"description": "True if the person has an avatar."
},
"fingerprint": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"enum": [
"christmasTree"
],
"description": "The unique name of the emoji"
},
"codePoint": {
"type": "number",
"enum": [
127876
],
"description": "The emoji's codepoint in Unicode"
},
"title": {
"type": "string",
"enum": [
"christmas tree"
],
"description": "The english translation key"
}
},
"required": [
"name",
"codePoint",
"title"
],
"additionalProperties": false
},
"description": "The persons fingerprint"
}
},
"required": [
"fingerprint"
]
}The UID token is missing or not valid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}No profile matches the given key.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Get the profile of a personGET/id/v2/public/profile/{key}?_uidt={uidToken}
Fetches the public profile of any person whose profile is stored in Skalio ID. The key must match any of the following fields to select a profile:
-
UID of the person
-
an email address of the person
Please note that only verified email addresses are evaluated. Search by UID is supported, even if the person has no verified email address.
The response contains the primary email address of the person if it has been verified. The field may be empty, if none of the email addresses have been verified.
- key
string(required) Example: 533h18.ygguv_b_0UID or a verified email address of a person
- uidToken
string(required) Example: abc123.ghi456.jkl789UID token
Headers
Content-Type: image/jpeg
Etag: "a1b2c3"Body
{... payload ...}The UID token is missing or not valid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}No profile and no organization matches the given key, or it does not have an avatar.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Get an avatarGET/id/v2/public/avatar/{uid}?height={height}&_uidt={uidToken}
Fetches the avatar of a person or organization. The key must match any of the following fields to select an avatar:
-
UID of the person
-
an email address of the person
-
UID of the organization
Please note that only verified email addresses are evaluated. Search by UID is supported, even if the person has no verified email address.
- uid
string(required)UID of a person or organization
- height
number(optional) Example: 80requested height of the image
- uidToken
string(required)UID token
Headers
Content-Type: application/json
Etag: "a1b2c3"Body
{
"uid": "n_gwumunrj77j-r0",
"name": "Example Inc",
"hasAvatar": true
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique ID of the organization."
},
"name": {
"type": "string",
"description": "The name of the organization, if set."
},
"hasAvatar": {
"type": "boolean",
"description": "True if the organization has an avatar."
}
},
"required": [
"uid",
"hasAvatar"
]
}The UID token is missing or not valid.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}No such entity.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Get an organizationGET/id/v2/public/organization/{uid}?_uidt={uidToken}
Fetches the public profile of an organization.
- uid
string(required)UID of an organization
- uidToken
string(required)UID token
Organizations ¶
Organization Management ¶
Requests must be authenticated with an access token. Modifications require authorization, such as membership in a group with administration privileges.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"uid": "n_gwumunrj77j-r0",
"hasAvatar": true,
"profile": {
"name": "Example Inc",
"addressLine1": "Hello, world!",
"addressLine2": "Hello, world!",
"postCode": "Hello, world!",
"city": "Hello, world!",
"state": "Hello, world!",
"country": "Hello, world!",
"phoneNumber": "Hello, world!"
},
"subscriptions": [
{
"orgUid": "n_gwumunrj77j-r0",
"createdAt": "2022-05-11T10:50:50Z",
"updated": "2022-05-11T10:50:50Z",
"expiresAt": "2022-06-17T12:46:56Z",
"status": "active",
"domain": "spaces",
"productId": "business",
"displayName": "Novospace Business"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique ID of the organization. Readonly."
},
"hasAvatar": {
"type": "boolean",
"description": "True if the organization has an avatar."
},
"profile": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the organization. Null if none has been set yet."
},
"addressLine1": {
"type": "string",
"description": "A part of the address of the organization."
},
"addressLine2": {
"type": "string",
"description": "A part of the address of the organization."
},
"postCode": {
"type": "string",
"description": "A part of the address of the organization."
},
"city": {
"type": "string",
"description": "A part of the address of the organization."
},
"state": {
"type": "string",
"description": "A part of the address of the organization."
},
"country": {
"type": "string",
"description": "A part of the address of the organization."
},
"phoneNumber": {
"type": "string",
"description": "A phone number for the organization."
}
},
"required": [
"name"
],
"description": "The profile of the organization."
},
"subscriptions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"orgUid": {
"type": "string",
"enum": [
"n_gwumunrj77j-r0"
],
"description": "Unique ID of the organization."
},
"createdAt": {
"type": "string",
"enum": [
"2022-05-11T10:50:50Z"
],
"description": "Timestamp when the subscription was initially created."
},
"updated": {
"type": "string",
"enum": [
"2022-05-11T10:50:50Z"
],
"description": "Timestamp when the subscription was last updated."
},
"expiresAt": {
"type": "string",
"enum": [
"2022-06-17T12:46:56Z"
],
"description": "Timestamp when the subscription gets cancelled. `null` if subscription is not cancelled."
},
"status": {
"type": "string",
"enum": [
"active",
"cancelled",
"incomplete",
"past_due",
"incomplete_expired",
"trialing",
"unpaid",
"active"
],
"description": "The current status of the subscription. Null, if the subscription is not yet referencing a product."
},
"domain": {
"type": "string",
"enum": [
"spaces",
"skp"
],
"description": "The domain of this product. Null, if the subscription is not yet referencing a product."
},
"productId": {
"type": "string",
"enum": [
"business"
],
"description": "The name of this product, unique in the domain. Null, if the subscription is not yet referencing a product."
},
"displayName": {
"type": "string",
"enum": [
"Novospace Business"
],
"description": "A user-presentable string for the product. Null, if the subscription is not yet referencing a product."
}
},
"required": [
"orgUid",
"createdAt",
"updated"
],
"additionalProperties": false
},
"description": "List of subscriptions"
}
},
"required": [
"uid",
"hasAvatar",
"profile",
"subscriptions"
]
}Insufficient authorization to access the organization.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Organization not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Fetch organizationGET/id/v2/organizations/{uid}
Returns the organization referenced by the uid.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Headers
Authorization: Bearer abcdef.123456.ghijklInsufficient authorization to delete the organization.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Delete organizationDELETE/id/v2/organizations/{uid}
Permanently deletes the organization referenced by the uid. The delete request is cascaded to other backend application, where related data might get deleted as well.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Profile Mangement ¶
Requests must be authenticated with an access token. Modifications require authorization, such as membership in a group with administration privileges.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"name": "Example Inc",
"addressLine1": "Hello, world!",
"addressLine2": "Hello, world!",
"postCode": "Hello, world!",
"city": "Hello, world!",
"state": "Hello, world!",
"country": "Hello, world!",
"phoneNumber": "Hello, world!"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the organization. Null if none has been set yet."
},
"addressLine1": {
"type": "string",
"description": "A part of the address of the organization."
},
"addressLine2": {
"type": "string",
"description": "A part of the address of the organization."
},
"postCode": {
"type": "string",
"description": "A part of the address of the organization."
},
"city": {
"type": "string",
"description": "A part of the address of the organization."
},
"state": {
"type": "string",
"description": "A part of the address of the organization."
},
"country": {
"type": "string",
"description": "A part of the address of the organization."
},
"phoneNumber": {
"type": "string",
"description": "A phone number for the organization."
}
},
"required": [
"name"
]
}Insufficient authorization to access the organization.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Organization not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Fetch profileGET/id/v2/organizations/{uid}/profile
Returns the profile of the organization referenced by the uid.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Headers
Authorization: Bearer abcdef.123456.ghijklBody
{
"name": "Example Inc",
"addressLine1": "Hello, world!",
"addressLine2": "Hello, world!",
"postCode": "Hello, world!",
"city": "Hello, world!",
"state": "Hello, world!",
"country": "Hello, world!",
"phoneNumber": "Hello, world!"
}Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the organization. Null if none has been set yet."
},
"addressLine1": {
"type": "string",
"description": "A part of the address of the organization."
},
"addressLine2": {
"type": "string",
"description": "A part of the address of the organization."
},
"postCode": {
"type": "string",
"description": "A part of the address of the organization."
},
"city": {
"type": "string",
"description": "A part of the address of the organization."
},
"state": {
"type": "string",
"description": "A part of the address of the organization."
},
"country": {
"type": "string",
"description": "A part of the address of the organization."
},
"phoneNumber": {
"type": "string",
"description": "A phone number for the organization."
}
},
"required": [
"name"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}Headers
Content-Type: application/jsonBody
{
"name": "Example Inc",
"addressLine1": "Hello, world!",
"addressLine2": "Hello, world!",
"postCode": "Hello, world!",
"city": "Hello, world!",
"state": "Hello, world!",
"country": "Hello, world!",
"phoneNumber": "Hello, world!"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the organization. Null if none has been set yet."
},
"addressLine1": {
"type": "string",
"description": "A part of the address of the organization."
},
"addressLine2": {
"type": "string",
"description": "A part of the address of the organization."
},
"postCode": {
"type": "string",
"description": "A part of the address of the organization."
},
"city": {
"type": "string",
"description": "A part of the address of the organization."
},
"state": {
"type": "string",
"description": "A part of the address of the organization."
},
"country": {
"type": "string",
"description": "A part of the address of the organization."
},
"phoneNumber": {
"type": "string",
"description": "A phone number for the organization."
}
},
"required": [
"name"
]
}Insufficient authorization to update the organization.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Organization not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Update profilePUT/id/v2/organizations/{uid}/profile
Updates the profile of the organization referenced by the uid. Requires admin privileges.
Updating the profile triggers a SignalingEvent of type ORGANIZATION_PROFILE_UPDATED into the feed of all members of the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Avatar Mangement ¶
A person can upload an image to represent the organization in public. The avatar image can later be requested without authorization by querying the public avatar resource.
Requests must be authenticated with an access token. Modifications require authorization, such as membership in a group with administration privileges.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: image/jpeg
Etag: "213508"Body
{... payload ...}Insufficient authorization to access the organization.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Organization not found. No avatar has been uploaded.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Get AvatarGET/id/v2/organizations/{uid}/avatar?height={height}
Returns the organization’s avatar if one has been uploaded.
In addition to the Authorization header, this request alternatively accepts the valid access token in the form of a cookie with name acct. If both are present, the header will be evaluated only.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
- height
number(optional) Example: 80the requested size of the avatar image
Headers
Content-Type: image/jpg
Authorization: Bearer abcdef.123456.ghijklBody
{... payload ...}Headers
Content-Type: image/jpeg
Location: /id/v2/profile/avatarBody
{... payload ...}The image could not be processed.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Insufficient authorization to update the organization.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Organization not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Upload AvatarPUT/id/v2/organizations/{uid}/avatar
Uploading a new avatar requires admin privileges. The resource accept payload with the following content types only:
-
image/jpeg -
image/png -
image/gif
An uploaded avatar is cropped to a square size, resized and re-encoded to JPG.
Updating an avatar triggers a SignalingEvent of type ORGANIZATION_AVATAR_UPDATED into the feed of all members of the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Headers
Authorization: Bearer abcdef.123456.ghijklInsufficient authorization to update the organization.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Organization not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Delete AvatarDELETE/id/v2/organizations/{uid}/avatar
Removes the organization’s avatar if one has been uploaded. Requires admin privileges.
Deleting an avatar triggers a SignalingEvent of type ORGANIZATION_AVATAR_UPDATED into the feed of all members of the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Contractual documents ¶
An organization is the legal entity that enters a contractual relationship with Skalio. Documents that describe the relationship can be managed here.
Requests must be authenticated with an access token. Modifications require authorization, such as membership in a group with administration privileges.
Authentication via header
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/pdf
Content-Disposition: filename*=UTF-8''AV%20Vertrag%20Novospace%20Premium%20%28n_gwumunrj77j-r0%29.pdfBody
{... payload ...}A required parameter is missing or has an invalid value.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Insufficient authorization to access the organization. The organization does not have a valid subscription for the product. The organization is missing its profile.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Organization not found. The requested document type is not supported (yet).
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Authentication via cookie
Headers
Cookie: acct=abcdef.123456.ghijklHeaders
Content-Type: application/pdf
Content-Disposition: filename*=UTF-8''AV%20Vertrag%20Novospace%20Premium%20%28n_gwumunrj77j-r0%29.pdfBody
{... payload ...}A required parameter is missing or has an invalid value.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Insufficient authorization to access the organization. The organization does not have a valid subscription for the product. The organization is missing its profile.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Organization not found. The requested document type is not supported (yet).
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Fetch documentGET/id/v2/organizations/{uid}/documents?type={docType}&domain={domain}
Renders and returns a contractual document for the organization. Depending on the type of document, additional query parameters may be required.
Before any contract documents can be rendered, the organization profile must have been created.
The person must have admin-privileges on the organization.
| Document type | Required parameters | Note |
|---|---|---|
dataProcessing |
domain |
The organization must have an active subscription in that product domain. |
In addition to the Authorization header, this request alternatively accepts the valid access token in the form of a cookie with name acct. If both are present, the header will be evaluated only.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
- docType
LegalDocumentType(required) Example: dataProcessingThe type of document
- domain
ProductDomain(optional) Example: spacesRefers to a subscribed product. The parameter may be required, depending on the document type.
Products & Subscriptions ¶
Products ¶
Requests must be authenticated with an access token.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"products": [
{
"domain": "spaces",
"productId": "business",
"displayName": "Novospace Business",
"description": "1 TB Speicherplatz"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"domain": {
"type": "string",
"enum": [
"spaces",
"skp"
],
"description": "The domain of this product."
},
"productId": {
"type": "string",
"enum": [
"business"
],
"description": "The name of this product, unique in the domain."
},
"displayName": {
"type": "string",
"enum": [
"Novospace Business"
],
"description": "A name to display to users, not localized."
},
"description": {
"type": "string",
"enum": [
"1 TB Speicherplatz"
],
"description": "A text to display to users, not localized."
}
},
"required": [
"domain",
"productId"
],
"additionalProperties": false
}
}
},
"required": [
"products"
]
}List all productsGET/id/v2/products?domain={domain}
Returns a list of products registered in Skalio ID.
- domain
ProductDomain(optional) Example: spacesAn optional filter to limit listing of products
Subscriptions ¶
The principal must have admin privileges in the organization he is managing.
Requests must be authenticated with an access token.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"url": "https://billing.stripe.com/session/test_YWNjdF8xTEJhbWlKL",
"expiresAt": "2022-07-20T13:48:15Z"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The URL to the Stripe checkout or customer portal session."
},
"expiresAt": {
"type": "string",
"description": "If not null, the URL expires at this time."
}
},
"required": [
"url"
]
}Insufficient authorization to access the organization, or Stripe subscription exists already.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Organization or product not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Error during interaction with Stripe. Please retry.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Stripe Checkout SessionPOST/id/v2/subscriptions/stripe/{orgUid}/checkout/{domain}/{productId}
In order to purchase the initial subscription in product domain, a person can perform a checkout with Stripe. Note: an organization can have only one subscription in the given product domain. The checkout session expires after a short period of time, check the expiresAt field to be prepared.
- orgUid
string(required) Example: pep6umv2hzzhhj64The UID of the organization
- domain
ProductDomain(required) Example: spacesThe domain of the product
- productId
string(required) Example: businessThe ID of the product
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"url": "https://billing.stripe.com/session/test_YWNjdF8xTEJhbWlKL",
"expiresAt": "null"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The URL to the Stripe checkout or customer portal session."
},
"expiresAt": {
"type": [
"string",
"null"
],
"description": "If not null, the URL expires at this time."
}
},
"required": [
"url"
]
}Insufficient authorization to access the organization, or Stripe subscription is missing.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "This request is forbidden.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Organization not found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Error during interaction with Stripe. Please retry.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The data could not be stored.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Stripe Customer Portal SessionPOST/id/v2/subscriptions/stripe/{orgUid}/portal/{domain}
Once a subscription for the product domain exists, it can be managed in the Stripe Customer Portal. A session can be requested here. The expiresAt field of the session is always null.
- orgUid
string(required) Example: pep6umv2hzzhhj64The UID of the organization
- domain
ProductDomain(required) Example: spacesThe domain of the product
Headers
Stripe-Signature: t=1657712964,v1=042f971bf4e348dc0bdba7d557100196ae4127aea2dad7211e65df9446f0bcb8,v0=6632de3a68b216e69ad451a9986e0c1669fc2bc6e22f95ce39f5a4f4ebfe3657.Body
{
"id": "evt_1LL44GJXiQM2QqDHF8LVf4sc",
"object": "event",
"api_version": "2020-08-27",
"created": 1657712964,
"data": {
...
},
"livemode": false,
"pending_webhooks": 2,
"request": {
"id": "req_w14UUe3JUFTChi",
"idempotency_key": "3acbc3ad-4e68-4833-9247-ab333649bc5e"
},
"type": "billing_portal.session.created"
}Data cannot be parsed, or signature verification failed.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Stripe Event Webhook EndpointPOST/id/v2/subscriptions/stripe/webhook
An endpoint where Stripe can post events as webhooks to. Events are verified against the Stripe-Signature and persisted into the database.
Feedback ¶
Submit feedback ¶
Requests must be authenticated with a UID token.
Headers
Content-Type: application/jsonBody
{
"productId": "spaces",
"email": "bob@example.test",
"name": "Horst Groby",
"stars": 3,
"issues": [
"works well",
"fast speed"
],
"context": [
"de_DE",
"iOS"
],
"comment": "I love it",
"type": "manual"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"productId": {
"type": "string",
"enum": [
"spaces",
"skp"
],
"description": "The ID of the product the feedback relates to."
},
"email": {
"type": "string",
"description": "The email address of the person who provided the feedback."
},
"name": {
"type": "string",
"description": "The name of the person who provided the feedback."
},
"stars": {
"type": "number",
"description": "Value must be 0 < x <= 5. Denominates happiness with the product."
},
"issues": {
"type": [
"array",
"null"
],
"description": "A number of tags that the user selects describing his problems or satisfactions."
},
"context": {
"type": [
"array",
"null"
],
"description": "A number of tags that the client selects describing the context of the feedback."
},
"comment": {
"type": [
"string",
"null"
],
"description": "End user comment."
},
"type": {
"type": "string",
"enum": [
"manual",
"eventDriven",
"supportRequest"
],
"description": "The type of submitted feedback."
}
},
"required": [
"productId"
]
}Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "Authentication failed or missing.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Headers
Content-Type: application/jsonBody
{
"error": {
"code": 429002,
"message": "Maximum number of concurrent API requests reached.",
"details": [
"Hello, world!",
"Please try again after waiting some time."
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Submit feedbackPOST/id/v2/feedback?_uidt={uidToken}
Applications can submit user feedback for analysis by Skalio staff.
This resource is rate-limit protected. A person may submit up to one feedback per minute.
Note: email must be provided when submitting support requests.
Note: stars must be provided when submitting feedback requests.
- uidToken
string(required) Example: abc123.ghi456.jkl789UID token
Legal Documents ¶
Fetch a document ¶
Legal documents, such as terms & conditions or the privacy policy are made available through the legal-documents resource.
Headers
Content-Type: text/plainBody
{... payload ...}The type is not supported
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The request cannot be fulfilled.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}The productId or type could not be found.
Headers
Content-Type: application/jsonBody
{
"error": {
"code": 0,
"message": "The requested object does not exist.",
"details": [
"Hello, world!"
]
}
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "number",
"description": "The error code"
},
"message": {
"type": "string",
"description": "English error message."
},
"details": {
"type": "array",
"description": "English details to error."
}
}
}
}
}Fetch documentGET/id/v2/legal/{productId}/{type}
Fetches a legal document of the given type for the requested product.
Supported product IDs:
com.skalio.spaces: refers to the Novospace product
Supported document types:
-
terms: The terms and conditions. -
dataProcessing: The data processing agreement. -
privacyPolicy: The privacy policy. -
imprint: Contact details of Skalio GmbH.
The content type of the returned document may vary, depending on what is stored. Possible values are:
-
text/plain -
application/pdf
Access to this resource currently does not require authentication.
- productId
LegalProductId(required) Example: com.skalio.spaces- type
LegalDocumentType(required) Example: privacyPolicy
Generated by aglio on 08 Apr 2024