API Documentation
API Endpoint
https://free.teambeam.de/apiSkalio ID API Version 3 ¶
Welcome to the Skalio ID API, offering access to the Skalio ID project service. This document describes version 3 of the API.
Changelog ¶
Major changes between v2 and v3: ¶
Version 2 has been deprecated on 2023-04-14. 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 v3 branch is highly recommended.
-
Signup no longer automatically creates organization and membership for the new person. A person must create or join an organization. Membership with a single organization is supported.
-
The ID token contains a
verclaim, with value"3.0". This should help decoding the structure of tokens. -
The ID token no longer holds the
orgUnitsclaim. Instead the ID token contains thehttp://skalio.com/org_idandrolesclaims, describing organization membership and respective privileges. -
An organization admin can manage its members by assigning roles.
-
A person can join an organization by accepting an invitation.
-
Upgrading an ID token is possible at any time. Depending on the circumstances, the claims of the ID token may not necessarily change. It can be seen as a refresh of the ID token.
-
An ID token can be parked and picked up again. This is helpful when redirecting authenticated persons to a different domain names in a web-browser.
-
Delay tokens have been removed. They are no longer issued or required.
Major changes between v1 and v2: ¶
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.
-
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/v3
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. With a valid ID token, an access token can be obtained.
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.
Tokens are provided in the Authorization header of the HTTP request. Example:
> GET /id/v3/profile HTTP/2
> Host: id.skalio.dev
> user-agent: insomnia/2023.4.0
> authorization: Bearer eyJraWQiOiI5ZnVkMmw4XzlkX3BpMncxIiwiYWxnIjoiRVMyNTYiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwOi8vc2thbGlvLmNvbSIsImF1ZCI6Imh0dHA6Ly9za2FsaW8uY29tL2lkIiwic3ViIjoiOXpwd3JvaGQ0NWxqbHF5MCIsImV4cCI6MTcwMTA4MTI3OSwic2lkIjoiXzhzcWo2eXVydThmaDg4diIsInNjb3BlIjoiYWNjZXNzIiwicm9sZXMiOlsiT3JnYW5pemF0aW9uLkFkbWluIiwiU2VydmljZS5BbGwuVXNlIl19.st1e7O2qyq9Q6xYoq8E4sZ1Elst8n_4M9yH73HOGVwXcZTP2VrKV8ir8FjKm41EICd36lXeCYYaGl3My3PAjgw
> accept: */*
< HTTP/2 200
< ... response ...
In some cases, the backend may blacklist and recreate an ID token for the principal as a consequence of a request. The newly issued ID token can be found in the Authorization header in the response.
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/v3/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/json
Authorization: Bearer mnopqr.7890123.stuvwxBody
{
"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/v3/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.
The ID token is also delivered via the Authorization header.
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/v3/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/v3/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/json
Authorization: Bearer mnopqr.7890123.stuvwxBody
{
"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/v3/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.
The ID token is also delivered via the Authorization header.
If the external ID token matches a Skalio ID organization, the person becomes a member of that organization. This may fail if the organization’s member limit has been reached, in which case the authentication fails.
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/json
Authorization: Bearer mnopqr.7890123.stuvwxBody
{
"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/v3/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.
The ID token is also delivered via the Authorization header.
If the external ID token matches a Skalio ID organization, the person becomes a member of that organization. This may fail if the organization’s member limit has been reached, in which case the authentication fails.
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/v3/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&session_state=x1y2z3&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/v3/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.
If the external ID token matches a Skalio ID organization, the person becomes a member of that organization. This may fail if the organization’s member limit has been reached, in which case the authentication fails.
Supported parameters:
-
state(string, required): references the state created during pre-flight request. -
id_token(string, required): the external JWT, identifying the person. -
session_state(string, optional): an optional reference to the session of the original identity provider from which the request was issued. If set, can be used for single-logout. -
user(JSON, optional): an optional JSON string, describing the details of the person. Only used by Apple. -
error(string, optional): if present, it indicates the request was not successful.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/json
Authorization: Bearer mnopqr.7890123.stuvwxBody
{
"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/v3/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.
The ID token is also delivered via the Authorization header.
Single LogoutGET/id/v3/oidc/auth/logout?sid={sessionId}
API endpoint supporting OIDC front-channel logout. An external identity provider can call this endpoint to terminate all local sessions (= ID tokens) issued from within its session.
Only works, if the IDP previously issued ID tokens containing an sid claim, or specified the session_state in the form-post flow.
If a matching external session ID exists, all related Skalio ID tokens are blacklisted.
- sessionId
string(required) Example: x1y2z3The external session ID.
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/v3/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
{
"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.
Headers
Content-Type: application/jsonBody
{
"provider": "http://skalio.com"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"http://skalio.com",
"https://appleid.apple.com",
"https://accounts.google.com"
],
"description": "References the identity provider of the person."
}
},
"required": [
"provider"
]
}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/v3/auth/exists
Checks whether an email address exists within Skalio ID, i.e. is associated with a Skalio ID person.
Clients can use the response to control the sign-in/sign-up process:
-
select the identity provider to authenticate against
-
correctly chose sign-in vs sign-up as the next step
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/json
Authorization: Bearer mnopqr.7890123.stuvwxBody
{
"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/json
Authorization: Bearer mnopqr.7890123.stuvwxBody
{
"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/v3/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.
The ID token is also delivered via the Authorization header.
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/v3/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/v3/auth/uid
Creates a new uid token. The token has a long lifetime and is used to identify 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/json
Authorization: Bearer mnopqr.7890123.stuvwxBody
{
"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."
}
}
}
}
}Upgrade ID tokenPOST/id/v3/auth/upgrade
Replaces the given ID token with a new ID token. The ID token used to authenticate this request is blacklisted. A token can be upgraded at any time.
Depending on the circumstances, the claims of the new ID token may have changed:
-
Verifying a previously unverified email address results in a higher
authLevel. -
Changes in memberships of organizations are reflected in the
rolesclaim. -
The expiration time of the original ID token is transferred to the refreshed token, unless the
authLevelis changed.
The ID token is also delivered via the Authorization header.
Requests must be authenticated with an ID token.
Headers
Authorization: Bearer abcdef.123456.ghijklThe ID token was accepted and a pickup token is issued in return. The original ID token is blacklisted.
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 ID 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."
}
}
}
}
}No person found matching the ID token.
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."
}
}
}
}
}Park ID tokenPOST/id/v3/auth/park
Exchanges the ID token against a short-lived single-use pickup token with scope park.
In the process, the ID token is actually blacklisted and can no longer be used. When retrieving the parked ID token, a new token is issued.
Requests must be authenticated with an ID token.
Headers
Authorization: Bearer abcdef.123456.ghijklThe pickup token was accepted and a new ID token is issued.
Headers
Content-Type: application/json
Authorization: Bearer mnopqr.7890123.stuvwxBody
{
"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 pickup 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."
}
}
}
}
}No parked token or person found matching the pickup token.
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."
}
}
}
}
}Retrieve parked ID tokenGET/id/v3/auth/park
Returns the parked ID token previously handed in during the park request.
Since the original ID token was blacklisted during the park-request, the backend will issue a new ID token, but with the original validity time.
The ID token is also delivered via the Authorization header.
Requests must be authenticated with a pickup token with scope park.
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/v3/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/v3/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. The person has no password-based authenticator.
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/v3/auth/reset
Triggers the password recovery process. The person must provide an existing, verified email address. The person must have a bcrypt authenticator.
Headers
Content-Type: application/json
Authorization: Bearer mnopqr.7890123.stuvwxBody
{
"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/v3/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.
The ID token is also delivered via the Authorization header.
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
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"
}
],
"membership": {
"organization": {
"uid": "n_gwumunrj77j-r0",
"name": "Example Inc",
"hasAvatar": true,
"selfSignup": false,
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"globalSignature": "Hello, world!",
"legalNoticeUrl": "https://www.example.test/imprint/",
"privacyPolicyUrl": "https://www.example.test/privacy/",
"hostname": "teambeam.example.test",
"mfaRequired": false
},
"roles": [
"Organization.Admin"
]
}
}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"
},
"membership": {
"type": "object",
"properties": {
"organization": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique ID of the organization."
},
"name": {
"type": "string",
"description": "The name of the organization."
},
"hasAvatar": {
"type": "boolean",
"description": "True if the organization has an avatar."
},
"selfSignup": {
"type": "boolean",
"description": "Shows if the organization allows self-signup. This is true for the \"free\" organization."
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The default locale of the organization."
},
"timeZone": {
"type": "string",
"description": "The default time zone of the organization."
},
"globalSignature": {
"type": "string",
"description": "A corporate email signature."
},
"legalNoticeUrl": {
"type": "string",
"description": "A URL pointing to a legal notice document."
},
"privacyPolicyUrl": {
"type": "string",
"description": "A URL pointing to a privacy policy document."
},
"hostname": {
"type": "string",
"description": "The active hostname where the service for the organization is hosted."
},
"mfaRequired": {
"type": "boolean",
"description": "Shows if the organization requires members to use multi-factor authentication."
}
},
"required": [
"uid",
"name",
"hasAvatar",
"selfSignup",
"locale",
"timeZone",
"mfaRequired"
]
},
"roles": {
"type": "array",
"items": {
"type": "string",
"enum": [
"Organization.Admin",
"Contract.Admin",
"Contract.Read",
"Service.Transfer.Use",
"Service.Transfer.Archive.CreateRoot",
"Service.Drive.CreateSpace",
"Service.All.Use",
"Service.Spaces.Use"
]
},
"description": "List of roles the person has in the organization; can be empty"
}
},
"required": [
"roles"
],
"description": "Membership of an organization, or null if not a member"
}
},
"required": [
"fingerprint",
"emails"
]
}Get ProfileGET/id/v3/profile
This returns the complete profile of the principal.
Requests must be authenticated with an access token.
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"
}
],
"membership": {
"organization": {
"uid": "n_gwumunrj77j-r0",
"name": "Example Inc",
"hasAvatar": true,
"selfSignup": false,
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"globalSignature": "Hello, world!",
"legalNoticeUrl": "https://www.example.test/imprint/",
"privacyPolicyUrl": "https://www.example.test/privacy/",
"hostname": "teambeam.example.test",
"mfaRequired": false
},
"roles": [
"Organization.Admin"
]
}
}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"
},
"membership": {
"type": "object",
"properties": {
"organization": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique ID of the organization."
},
"name": {
"type": "string",
"description": "The name of the organization."
},
"hasAvatar": {
"type": "boolean",
"description": "True if the organization has an avatar."
},
"selfSignup": {
"type": "boolean",
"description": "Shows if the organization allows self-signup. This is true for the \"free\" organization."
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The default locale of the organization."
},
"timeZone": {
"type": "string",
"description": "The default time zone of the organization."
},
"globalSignature": {
"type": "string",
"description": "A corporate email signature."
},
"legalNoticeUrl": {
"type": "string",
"description": "A URL pointing to a legal notice document."
},
"privacyPolicyUrl": {
"type": "string",
"description": "A URL pointing to a privacy policy document."
},
"hostname": {
"type": "string",
"description": "The active hostname where the service for the organization is hosted."
},
"mfaRequired": {
"type": "boolean",
"description": "Shows if the organization requires members to use multi-factor authentication."
}
},
"required": [
"uid",
"name",
"hasAvatar",
"selfSignup",
"locale",
"timeZone",
"mfaRequired"
]
},
"roles": {
"type": "array",
"items": {
"type": "string",
"enum": [
"Organization.Admin",
"Contract.Admin",
"Contract.Read",
"Service.Transfer.Use",
"Service.Transfer.Archive.CreateRoot",
"Service.Drive.CreateSpace",
"Service.All.Use",
"Service.Spaces.Use"
]
},
"description": "List of roles the person has in the organization; can be empty"
}
},
"required": [
"roles"
],
"description": "Membership of an organization, or null if not a member"
}
},
"required": [
"fingerprint",
"emails"
]
}Update ProfilePUT/id/v3/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.
Requests must be authenticated with an access token.
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/v3/profile
Deletes the account permanently. Cascades to other applications.
Requests must be authenticated with an access token.
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.
Headers
Content-Type: image/jpg
Authorization: Bearer abcdef.123456.ghijklBody
{... payload ...}Headers
Content-Type: image/jpeg
Location: /id/v3/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/v3/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 multiple times and re-encoded to JPG:
-
500x500
-
240x240
-
160x160
-
80x80
Updating an avatar triggers a SignalingEvent of type PROFILE_AVATAR_UPDATED into the feed of interested persons.
Requests must be authenticated with an access token.
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/v3/profile/avatar?height={height}
Return the avatar of the principal, if one has been uploaded.
Avatars get resized only during the upload of a new image. When requesting a specific height, the backend attempts to deliver the closest matching image, but will not resize it exactly to the requested dimensions.
Requests must be authenticated with an access token. The token may be provided in the Authorization header or 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/v3/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.
Requests must be authenticated with an access token.
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.
Requesting and confirming verification of an email address is heavily rate-limited.
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/v3/profile/emails
Lists all email addresses of the person.
Requests must be authenticated with an access token.
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/v3/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/v3/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.
The primary address used during signup must be verified before additional addresses can be registered.
Requests must be authenticated with an access token.
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/v3/profile/emails/{address}
Removes the requested address. Throws an error, if the requested address is marked as primary or belongs to someone else.
Requests must be authenticated with an access token.
- 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/v3/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.
Requests must be authenticated with an access token.
- address
string(required) Example: bob@example.org
Headers
Authorization: Bearer abcdef.123456.ghijklThe requested email address is not found or belongs to another person.
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."
}
}
}
}
}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/v3/profile/emails/{address}/verify
Requests verification of the email address again. Renders all previously sent verification messages regarding this email invalid. This sends an email to the requested address containing a short verification key. The key is short-lived and is to be returned via the Confirm Address Verification endpoint.
Note: if the address has been verified already, this request is successful, but will not trigger a new verification message.
The resource is heavily rate-limit-protected. The person can trigger verification at most once per minute.
Requests must be authenticated with an access token.
- address
string(required) Example: bob@example.org
Headers
Authorization: Bearer abcdef.123456.ghijklThe email address has been verified.
Headers
Authorization: Bearer ...new ID token...The requested confirmation key 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."
}
}
}
}
}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."
}
}
}
}
}Confirm Address VerificationPOST/id/v3/confirm/{key}
Completes the verification of an email address.
The resource is heavily rate-limit-protected. The person can send confirmation requests at most once per minute.
If this request verifies the first registered address, the response contains an updated ID token in the Authorization header. This can be used to replace the existing ID token without the need to use the upgrade resource.
Requests must be authenticated with an access token.
- key
string(required) Example: A3CLConfirmation 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 |
| recovery | Small number of one-time passcodes with unlimited expiration | 0 or more |
When an authenticator of type recovery is registered, the system will actually create a small number of individual recovery codes. Used recovery codes are removed from the system. The number of available recovery codes is visible in the cardinality field. When all recovery codes are are used in an authentication request or the authenticator is unregistered, the authenticator disappears.
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",
"cardinality": 1
}
]
}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 server-generated key to a newly registered authenticator. Only shown once, during registration."
},
"dataUri": {
"type": "string",
"enum": [
"null"
],
"description": "This may include an image in data-URI format, representing the key of a newly registered authenticator."
},
"cardinality": {
"type": "number",
"enum": [
1
],
"description": "Details the number of available authenticators of this type."
}
},
"required": [
"type",
"uid",
"registeredAt",
"updatedAt",
"verified",
"cardinality"
],
"additionalProperties": false
}
}
},
"required": [
"authenticators"
]
}Get registered authenticatorsGET/id/v3/profile/authenticators
Returns a list of all registered, verified authenticators of the person.
Requests must be authenticated with an access token.
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/v3/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...",
"cardinality": 1
}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 server-generated key to a newly registered authenticator. Only shown once, during registration."
},
"dataUri": {
"type": "string",
"description": "This may include an image in data-URI format, representing the key of a newly registered authenticator."
},
"cardinality": {
"type": "number",
"description": "Details the number of available authenticators of this type."
}
},
"required": [
"type",
"cardinality"
]
}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. A security requirement for registration of authenticators is not met.
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/v3/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",
"cardinality": "3"
}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 server-generated key to a newly registered authenticator. Only shown once, during registration."
},
"dataUri": {
"type": "string",
"description": "This may include an image in data-URI format, representing the key of a newly registered authenticator."
},
"cardinality": {
"type": "string",
"description": "Details the number of available authenticators of this type."
}
},
"required": [
"type",
"cardinality"
]
}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. A security requirement for registration of authenticators is not met.
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/v3/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.
Security protocol requires that the person has a “young” session, and has recently verified their primary email address. Specific ForbiddenExceptions will indicate, if a requirement was not met. The person then needs to resolve the requirement and retry the registration of the authenticator. Error codes:
-
403134, Session too old: Authenticate again, fetch new access token, then retry. -
403133, Email address verification required again: A confirmation code has been sent to the primary email address. Confirm the address again, then retry.
Requests must be authenticated with an access token.
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"
}
}
}Headers
Authorization: Bearer ...new ID token...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/v3/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.
If this request verifies the first additional authenticator, the response contains an updated ID token in the Authorization header. This can be used to replace the existing ID token without the need to use the upgrade resource.
Requests must be authenticated with an access token.
- 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",
"cardinality": 1
}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 server-generated key to a newly registered authenticator. Only shown once, during registration."
},
"dataUri": {
"type": "string",
"description": "This may include an image in data-URI format, representing the key of a newly registered authenticator."
},
"cardinality": {
"type": "number",
"description": "Details the number of available authenticators of this type."
}
},
"required": [
"type",
"cardinality"
]
}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/v3/profile/authenticators/{uid}
Returns the referenced authenticator.
Requests must be authenticated with an access token.
- 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",
"cardinality": 1
}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 server-generated key to a newly registered authenticator. Only shown once, during registration."
},
"dataUri": {
"type": "string",
"description": "This may include an image in data-URI format, representing the key of a newly registered authenticator."
},
"cardinality": {
"type": "number",
"description": "Details the number of available authenticators of this type."
}
},
"required": [
"type",
"cardinality"
]
}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/v3/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.
Requests must be authenticated with an access token.
- 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/v3/profile/authenticators/{uid}
Removes the authenticator, if the type allows for this.
Requests must be authenticated with an access token.
- uid
string(required) Example: 'a8as9ykd_0s93'The uid of the authenticator.
Invitations ¶
Invitations ¶
An invitation allows a person to join an organization with a set of privileges. Since a person can only be member of one organization at a time, in order to accept an invitation, a person must first end their current membership.
An invitation can be shared or personalized:
-
shared: A public, reusable invitation to join a public organization. Typically this is used to join the “free” organization.
-
personalized: The organization admin issues the invitation, specifying the email address of the invitee.
- The invitee receives an email notification.
- In order to accept the invitation, the person must have the specified address in his list of verified email addresses.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"invitations": [
{
"key": "u7u1kzz8hq",
"shared": true,
"inviterUid": "533h18.ygguv_b_0",
"roles": [
"Organization.Admin"
],
"organization": {
"uid": "n_gwumunrj77j-r0",
"name": "Example Inc",
"hasAvatar": true,
"selfSignup": false,
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"globalSignature": "Hello, world!",
"legalNoticeUrl": "https://www.example.test/imprint/",
"privacyPolicyUrl": "https://www.example.test/privacy/",
"hostname": "teambeam.example.test",
"mfaRequired": false
}
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"invitations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"enum": [
"u7u1kzz8hq"
],
"description": "Identifies the invitation."
},
"shared": {
"type": "boolean",
"enum": [
false
],
"description": "True, if it is a shared invitation."
},
"inviterUid": {
"type": "string",
"enum": [
"533h18.ygguv_b_0"
],
"description": "Unique ID of the person that issued the invitation"
},
"roles": {
"type": "array",
"items": {
"type": "string",
"enum": [
"Organization.Admin",
"Contract.Admin",
"Contract.Read",
"Service.Transfer.Use",
"Service.Transfer.Archive.CreateRoot",
"Service.Drive.CreateSpace",
"Service.All.Use",
"Service.Spaces.Use"
]
},
"description": "List of roles that the invitation grants."
},
"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."
},
"hasAvatar": {
"type": "boolean",
"enum": [
false
],
"description": "True if the organization has an avatar."
},
"selfSignup": {
"type": "boolean",
"enum": [
false
],
"description": "Shows if the organization allows self-signup. This is true for the \"free\" organization."
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The default locale of the organization."
},
"timeZone": {
"type": "string",
"enum": [
"Europe/Berlin"
],
"description": "The default time zone of the organization."
},
"globalSignature": {
"type": "string",
"enum": [
""
],
"description": "A corporate email signature."
},
"legalNoticeUrl": {
"type": "string",
"enum": [
"https://www.example.test/imprint/"
],
"description": "A URL pointing to a legal notice document."
},
"privacyPolicyUrl": {
"type": "string",
"enum": [
"https://www.example.test/privacy/"
],
"description": "A URL pointing to a privacy policy document."
},
"hostname": {
"type": "string",
"enum": [
"teambeam.example.test"
],
"description": "The active hostname where the service for the organization is hosted."
},
"mfaRequired": {
"type": "boolean",
"enum": [
false
],
"description": "Shows if the organization requires members to use multi-factor authentication."
}
},
"required": [
"uid",
"name",
"hasAvatar",
"selfSignup",
"locale",
"timeZone",
"mfaRequired"
],
"additionalProperties": false,
"description": "The public profile of the organization that extends the invitation."
}
},
"required": [
"key",
"shared",
"roles",
"organization"
],
"additionalProperties": false
},
"description": "List of invitations"
}
},
"required": [
"invitations"
]
}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."
}
}
}
}
}Get available invitationsGET/id/v3/invitations
Fetches the list of invitations the person has access to.
Invitations may either be shared with anyone or specific to a person (personalized), in which case invitations are matched against verified email addresses of the person.
An invitation may reference the UID of the person that issued the invitation. If the inviter is removed later, the field is null.
Requests must be authenticated with an access token.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Authorization: Bearer new.idToken.123456The 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 invitation is blocked from acceptance. See above for possible reasons.
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."
}
}
}
}
}No invitation is found matching the 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."
}
}
}
}
}Accept an invitationPOST/id/v3/invitations/{key}/accept
Accepts the invitation. The person joins the organization, is granted privileges as defined by the invitation.
A person can join an organization only if
-
they are not currently members of an organization anywhere, or they are member of the “free” organization,
-
the
memberLimitof the target organization is not yet reached, -
for personal invitations: the email-address of the person matches the invitation.
Joining an organization while being member of the “free” organization replaces the membership. Afterwards, the person is member of only the joined organization.
Since the organization membership changes, the backend issues a new ID token and blacklists all previous tokens of the person. The new token is delivered via the Authorization header. It also results in a PRIVILEGES_UPDATED SignalingEvent to the person.
Requests must be authenticated with an access token.
- key
string(required) Example: u7u1kzz8hqThe invitation key.
Headers
Authorization: Bearer abcdef.123456.ghijklThe 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."
}
}
}
}
}A shared invitation cannot be rejected.
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."
}
}
}
}
}No invitation is found matching the 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."
}
}
}
}
}Rejects an invitationPOST/id/v3/invitations/{key}/reject
Removes a personalized invitation. It results in a INVITATION_ACTIVITY SignalingEvent to the person.
Requests must be authenticated with an access token.
- key
string(required) Example: u7u1kzz8hqThe invitation key.
Public ¶
Request public information ¶
It is possible for an authenticated person to retrieve public information about an entity. While the entity can be addressed by its unique ID, in some cases other search parameters are accepted, such as email.
Request are throttled. Caching and conditional GET requests are encouraged.
Requests may require authentication 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"
}
],
"locale": "de_DE",
"timeZone": "Europe/Berlin"
}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"
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The locale of the person"
},
"timeZone": {
"type": "string",
"description": "The person's timezone"
}
},
"required": [
"uid",
"hasAvatar",
"fingerprint",
"locale",
"timeZone"
]
}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."
}
}
}
}
}The profile exists, but the account is disabled.
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."
}
}
}
}
}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/v3/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.
Searching by email address requires a valid UID token. Search by UID does not require authentication.
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.
If the person is (temporarily) disabled, the server will return a ForbiddenException with response code 403.
- key
string(required) Example: alice@example.netUID or a verified email address of a person
- uidToken
string(optional) Example: abc123.ghi456.jkl789UID token (necessary for search)
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/v3/public/avatar/{key}?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.
Avatars get resized only during the upload of a new image. When requesting a specific height, the backend attempts to deliver the closest matching image, but will not resize it exactly to the requested dimensions. It is the responsibility of a frontend to render the image in the exact required dimensions.
Searching by email address requires a valid UID token. Search by UID does not require authentication.
- key
string(required)UID or a verified email address of a person, or UID of an organization
- height
number(optional) Example: 80requested height of the image
- uidToken
string(optional)UID token (necessary for search)
Headers
Content-Type: application/json
Etag: "a1b2c3"Body
{
"uid": "n_gwumunrj77j-r0",
"name": "Example Inc",
"hasAvatar": true,
"selfSignup": false,
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"globalSignature": "Hello, world!",
"legalNoticeUrl": "https://www.example.test/imprint/",
"privacyPolicyUrl": "https://www.example.test/privacy/",
"hostname": "teambeam.example.test",
"mfaRequired": false
}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."
},
"hasAvatar": {
"type": "boolean",
"description": "True if the organization has an avatar."
},
"selfSignup": {
"type": "boolean",
"description": "Shows if the organization allows self-signup. This is true for the \"free\" organization."
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The default locale of the organization."
},
"timeZone": {
"type": "string",
"description": "The default time zone of the organization."
},
"globalSignature": {
"type": "string",
"description": "A corporate email signature."
},
"legalNoticeUrl": {
"type": "string",
"description": "A URL pointing to a legal notice document."
},
"privacyPolicyUrl": {
"type": "string",
"description": "A URL pointing to a privacy policy document."
},
"hostname": {
"type": "string",
"description": "The active hostname where the service for the organization is hosted."
},
"mfaRequired": {
"type": "boolean",
"description": "Shows if the organization requires members to use multi-factor authentication."
}
},
"required": [
"uid",
"name",
"hasAvatar",
"selfSignup",
"locale",
"timeZone",
"mfaRequired"
]
}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/v3/public/organization/{key}
Fetches the public profile of an organization. The key must match any of the following fields:
-
UID of an organization
-
hostname of an organization (active or inactive)
- key
string(required)search term
Returns the logo.
Headers
Content-Type: image/png
Etag: "a1b2c3"Body
[...]Returns the theme.
Headers
Content-Type: application/json
Etag: "a1b2c3"Body
[...]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 organization assetGET/id/v3/public/assets/{type}
Fetches the asset of the organization. The organization is selected by matching against the request hostname.
The following asset types are supported:
-
logo: returns the organization’s logo asimage/png -
theme: returns the organization’s theme as a JSON file
- type
AssetType(required)the type of asset
Organizations ¶
An organization represents the entity that enters a contractual relationship with Skalio. An organization can have a profile, an avatar, members and subscriptions.
A person can be a member of none or exactly one organization. A dedicated organization exists that holds all members of the “freemium” service offering. This is called the “free” organization. All other organizations are “customer” organizations.
Roles assigned to a person control the privileges with which they interact with the organization or use its services and resources.
Organization Management ¶
An organization admin can manage the organization profile, its members and invitations. The organization can be removed. A person can leave their own organization.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"mfaRequired": false,
"uid": "n_gwumunrj77j-r0",
"externalUid": "e607e95f-ad60-1c8e-a888-34a4ae2b8418",
"hasAvatar": false,
"profile": {
"name": "Example Inc",
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"legalNoticeUrl": "https://www.example.test/imprint/",
"privacyPolicyUrl": "https://www.example.test/privacy/",
"hostname": "teambeam.example.test",
"inactiveHostnames": [
"old.example.test"
]
},
"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"
}
],
"memberCount": 1,
"memberLimit": 5
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"mfaRequired": {
"type": "boolean",
"description": "Shows if the organization requires members to use multi-factor authentication."
},
"uid": {
"type": "string",
"description": "Unique ID of the organization. Readonly."
},
"externalUid": {
"type": "string",
"description": "Optional external UID. Typically a MS Entra tenant ID."
},
"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."
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The default locale of the organization."
},
"timeZone": {
"type": "string",
"description": "The default time zone of the organization."
},
"globalSignature": {
"type": "string",
"description": "A corporate email signature."
},
"legalNoticeUrl": {
"type": "string",
"description": "A URL pointing to a legal notice document."
},
"privacyPolicyUrl": {
"type": "string",
"description": "A URL pointing to a privacy policy document."
},
"hostname": {
"type": "string",
"description": "The active hostname where the service for the organization is hosted."
},
"inactiveHostnames": {
"type": "array",
"description": "Non-null, possibly empty array of no-longer-active hostnames of the organization."
}
},
"required": [
"name",
"locale",
"timeZone",
"inactiveHostnames"
],
"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"
},
"memberCount": {
"type": "number",
"description": "Number of members"
},
"memberLimit": {
"type": "number",
"description": "Max number of members"
}
},
"required": [
"mfaRequired",
"uid",
"hasAvatar",
"profile",
"subscriptions",
"memberCount",
"memberLimit"
]
}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/v3/organizations/{uid}
Returns the organization referenced by the uid.
Requests must be authenticated with an access token. To access this API endpoint, the principal must be a member of the organization, regardless of the assigned role.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Headers
Authorization: Bearer abcdef.123456.ghijklBody
{
"mfaRequired": false
}Schema
{
"type": "object",
"properties": {
"mfaRequired": {
"type": "boolean",
"description": "Shows if the organization requires members to use multi-factor authentication."
}
},
"required": [
"mfaRequired"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}Headers
Content-Type: application/jsonBody
{
"mfaRequired": false,
"uid": "n_gwumunrj77j-r0",
"externalUid": "e607e95f-ad60-1c8e-a888-34a4ae2b8418",
"hasAvatar": false,
"profile": {
"name": "Example Inc",
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"legalNoticeUrl": "https://www.example.test/imprint/",
"privacyPolicyUrl": "https://www.example.test/privacy/",
"hostname": "teambeam.example.test",
"inactiveHostnames": [
"old.example.test"
]
},
"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"
}
],
"memberCount": 1,
"memberLimit": 5
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"mfaRequired": {
"type": "boolean",
"description": "Shows if the organization requires members to use multi-factor authentication."
},
"uid": {
"type": "string",
"description": "Unique ID of the organization. Readonly."
},
"externalUid": {
"type": "string",
"description": "Optional external UID. Typically a MS Entra tenant ID."
},
"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."
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The default locale of the organization."
},
"timeZone": {
"type": "string",
"description": "The default time zone of the organization."
},
"globalSignature": {
"type": "string",
"description": "A corporate email signature."
},
"legalNoticeUrl": {
"type": "string",
"description": "A URL pointing to a legal notice document."
},
"privacyPolicyUrl": {
"type": "string",
"description": "A URL pointing to a privacy policy document."
},
"hostname": {
"type": "string",
"description": "The active hostname where the service for the organization is hosted."
},
"inactiveHostnames": {
"type": "array",
"description": "Non-null, possibly empty array of no-longer-active hostnames of the organization."
}
},
"required": [
"name",
"locale",
"timeZone",
"inactiveHostnames"
],
"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"
},
"memberCount": {
"type": "number",
"description": "Number of members"
},
"memberLimit": {
"type": "number",
"description": "Max number of members"
}
},
"required": [
"mfaRequired",
"uid",
"hasAvatar",
"profile",
"subscriptions",
"memberCount",
"memberLimit"
]
}Insufficient authentication-level or 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 organization detailsPUT/id/v3/organizations/{uid}
Updates technical details of the organization referenced by the uid.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within the organization and use multi-factor authentication.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Headers
Authorization: Bearer abcdef.123456.ghijklThe operation was successful. The person has left the organization, and a new ID token has been issued.
Headers
Authorization: Bearer mnopqr.7890123.stuvwxThe 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 organization 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."
}
}
}
}
}Leave organizationPOST/id/v3/organizations/{uid}/leave
A person can leave an organization if they are a member. This removes the person’s membership of the organization. The person’s account remains unchanged.
An organization must always have at least one person with role Organization.Admin assigned. If the “last administrator” attempts to leave the organization, the request is rejected. In this scenario, the person must either assign the role to someone else in the organization first, or remove the organization completely if no-one else is a member anymore.
Since the organization membership changes, the backend issues a new ID token and blacklists all previous tokens of the person. The new token is delivered via the Authorization header. It also results in a PRIVILEGES_UPDATED SignalingEvent to the person.
Requests must be authenticated with an access token.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Profile management ¶
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"name": "Example Inc",
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"legalNoticeUrl": "https://www.example.test/imprint/",
"privacyPolicyUrl": "https://www.example.test/privacy/",
"hostname": "teambeam.example.test",
"inactiveHostnames": [
"old.example.test"
]
}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."
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The default locale of the organization."
},
"timeZone": {
"type": "string",
"description": "The default time zone of the organization."
},
"globalSignature": {
"type": "string",
"description": "A corporate email signature."
},
"legalNoticeUrl": {
"type": "string",
"description": "A URL pointing to a legal notice document."
},
"privacyPolicyUrl": {
"type": "string",
"description": "A URL pointing to a privacy policy document."
},
"hostname": {
"type": "string",
"description": "The active hostname where the service for the organization is hosted."
},
"inactiveHostnames": {
"type": "array",
"description": "Non-null, possibly empty array of no-longer-active hostnames of the organization."
}
},
"required": [
"name",
"locale",
"timeZone",
"inactiveHostnames"
]
}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/v3/organizations/{uid}/profile
Returns the profile of the organization referenced by the uid.
Requests must be authenticated with an access token. To access this API endpoint, the principal must be a member of the organization, regardless of the assigned role.
- 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!",
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"globalSignature": "Hello, world!",
"legalNoticeUrl": "https://www.example.test/imprint/",
"privacyPolicyUrl": "https://www.example.test/privacy/"
}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."
},
"locale": {
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The default locale of the organization."
},
"timeZone": {
"type": "string",
"description": "The default time zone of the organization."
},
"globalSignature": {
"type": "string",
"description": "A corporate email signature."
},
"legalNoticeUrl": {
"type": "string",
"description": "A URL pointing to a legal notice document."
},
"privacyPolicyUrl": {
"type": "string",
"description": "A URL pointing to a privacy policy document."
}
},
"required": [
"name"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}Headers
Content-Type: application/jsonBody
{
"name": "Example Inc",
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"legalNoticeUrl": "https://www.example.test/imprint/",
"privacyPolicyUrl": "https://www.example.test/privacy/",
"hostname": "teambeam.example.test",
"inactiveHostnames": [
"old.example.test"
]
}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."
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The default locale of the organization."
},
"timeZone": {
"type": "string",
"description": "The default time zone of the organization."
},
"globalSignature": {
"type": "string",
"description": "A corporate email signature."
},
"legalNoticeUrl": {
"type": "string",
"description": "A URL pointing to a legal notice document."
},
"privacyPolicyUrl": {
"type": "string",
"description": "A URL pointing to a privacy policy document."
},
"hostname": {
"type": "string",
"description": "The active hostname where the service for the organization is hosted."
},
"inactiveHostnames": {
"type": "array",
"description": "Non-null, possibly empty array of no-longer-active hostnames of the organization."
}
},
"required": [
"name",
"locale",
"timeZone",
"inactiveHostnames"
]
}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/v3/organizations/{uid}/profile
Updates the profile of the organization referenced by the uid.
Updating the profile triggers a SignalingEvent of type ORGANIZATION_PROFILE_UPDATED into the feed of all members of the organization.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Asset Management ¶
A person can upload several assets to an organization. These can be used when branding a webpage or client, or in an email.
The following asset types are supported:
-
logo: returns the organization’s log asimage/png -
theme: returns the organization’s theme as a JSON file
Asset management requires the principal to have the Organization.Admin role within the selected organization. Alternatively, a person with role Cluster.AssetManagement can manage the assets of a foreign organization.
Headers
Authorization: Bearer abcdef.123456.ghijklReturns the logo.
Headers
Content-Type: image/png
Etag: "a1b2c3"Body
[...]Returns the theme.
Headers
Content-Type: application/json
Etag: "a1b2c3"Body
[...]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 AssetGET/id/v3/organizations/{uid}/assets/{type}
Fetches an asset of the organization.
The following asset types are supported:
-
logo: returns the organization’s logo asimage/png -
theme: returns the organization’s theme as a JSON file
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
- type
AssetType(required)the type of asset
Upload a logo.
Headers
Content-Type: multipart/form-data; boundary=abc123
Authorization: Bearer abcdef.123456.ghijklBody
--abc123
Content-Disposition: form-data; name="file"
Content-Type: image/jpeg
JPEG {... binary data ...}
--abc123Returns the logo.
Headers
Content-Type: image/png
Etag: "a1b2c3"Body
[...]Upload the theme.
Headers
Content-Type: multipart/form-data; boundary=abc123
Authorization: Bearer abcdef.123456.ghijklBody
--abc123
Content-Disposition: form-data; name="file"
Content-Type: application/json
{
"version": "v1.0",
"backgroundColor": "#bebebe",
...
}
--abc123Returns the theme.
Headers
Content-Type: application/json
Etag: "a1b2c3"Body
[...]The payload is not supported or cannot be parsed.
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."
}
}
}
}
}Not authorized to update the asset.
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 assetPOST/id/v3/organizations/{uid}/assets/{type}
Uploads an asset to the organization. The endpoint accepts multipart-formdata requests and expectes the payload in a formdata-part named file.
The following asset types are supported:
-
logo: acceptsimage/*, re-encodes it asimage/png- The image must be larger than 10x10 pixels.
- If the image is larger than 1000x110, it is resized into this container, keeping the aspect ratio intact.
-
theme: accepts and validates JSON
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
- type
AssetType(required)the type of asset
Headers
Authorization: Bearer abcdef.123456.ghijklInsufficient authorization to manage the organization’s assets.
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 assetDELETE/id/v3/organizations/{uid}/assets/{type}
Deletes the asset from the organization.
The following asset types are supported:
-
logo: the organization’s logo -
theme: the organization’s theme file
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
- type
AssetType(required)the type of asset
Avatar Management ¶
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.
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/v3/organizations/{uid}/avatar?height={height}
Returns the organization’s avatar if one has been uploaded.
Avatars get resized only during the upload of a new image. When requesting a specific height, the backend attempts to deliver the closest matching image, but will not resize it exactly to the requested dimensions.
Requests must be authenticated with an access token. The token may be provided in the Authorization header or in the form of a cookie with name acct. If both are present, the header will be evaluated only.
To access this API endpoint, the principal must be a member of the organization, regardless of the assigned role.
- 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/v3/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/v3/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 multiple times and re-encoded to JPG:
-
500x500
-
240x240
-
160x160
-
80x80
Updating an avatar triggers a SignalingEvent of type ORGANIZATION_AVATAR_UPDATED into the feed of all members of the organization.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within 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/v3/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.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within 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.
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/v3/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. |
Requests must be authenticated with an access token. The token may be provided in the Authorization header or in the form of a cookie with name acct. If both are present, the header will be evaluated only.
To access this API endpoint, the principal must be a member of the organization, regardless of the assigned role.
- 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.
Membership management ¶
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"members": [
{
"uid": "533h18.ygguv_b_0",
"externalUid": "a03a45b7-2a14-c789-23a6-a9c6c8e42136",
"externalIdentityProvider": "https://login.microsoftonline.com/common/v2.0",
"name": "Horst Groby",
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"hasAvatar": true,
"createdAt": "2022-05-11T10:50:50Z",
"lastLoginAt": "2022-06-17T12:46:56Z",
"emails": [
{
"address": "bob@example.org",
"primary": true,
"verified": true,
"removeAt": "null"
}
],
"roles": [
"Organization.Admin"
],
"reference": "Hello, world!"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"members": {
"type": "array",
"items": {
"type": "object",
"properties": {
"uid": {
"type": "string",
"enum": [
"533h18.ygguv_b_0"
],
"description": "Unique ID of the person"
},
"externalUid": {
"type": "string",
"enum": [
"a03a45b7-2a14-c789-23a6-a9c6c8e42136"
],
"description": "Optional external UID, as defined by the external identity provider. `null` for local users."
},
"externalIdentityProvider": {
"type": "string",
"enum": [
"https://login.microsoftonline.com/common/v2.0"
],
"description": "Optional issuer-string of the identity provider that covers this person."
},
"name": {
"type": "string",
"enum": [
"Horst Groby"
],
"description": "Name of person, if set."
},
"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",
"enum": [
"Europe/Berlin"
],
"description": "The person's timezone."
},
"hasAvatar": {
"type": "boolean",
"enum": [
true
],
"description": "True if the person has an avatar."
},
"createdAt": {
"type": "string",
"enum": [
"2022-05-11T10:50:50Z"
],
"description": "Timestamp when the person was created"
},
"lastLoginAt": {
"type": "string",
"enum": [
"2022-06-17T12:46:56Z"
],
"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"
},
"roles": {
"type": "array",
"items": {
"type": "string",
"enum": [
"Organization.Admin",
"Contract.Admin",
"Contract.Read",
"Service.Transfer.Use",
"Service.Transfer.Archive.CreateRoot",
"Service.Drive.CreateSpace",
"Service.All.Use",
"Service.Spaces.Use"
]
},
"description": "List of roles the person has in the organization; can be empty"
},
"reference": {
"type": "string",
"enum": [
""
],
"description": "Optional reference string, visible only to the organization admin."
}
},
"required": [
"uid",
"locale",
"timeZone",
"hasAvatar",
"createdAt",
"lastLoginAt",
"emails",
"roles"
],
"additionalProperties": false
},
"description": "List of members of the organization"
}
},
"required": [
"members"
]
}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."
}
}
}
}
}List all membersGET/id/v3/organizations/{uid}/members
Returns all members of the selected organization.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Headers
Authorization: Bearer abcdef.123456.ghijklBody
{
"uid": "533h18.ygguv_b_0",
"roles": [
"Organization.Admin"
],
"reference": "Hello, world!"
}Schema
{
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique ID of the person"
},
"roles": {
"type": "array",
"items": {
"enum": [
"Organization.Admin",
"Contract.Admin",
"Contract.Read",
"Service.Transfer.Use",
"Service.Transfer.Archive.CreateRoot",
"Service.Drive.CreateSpace",
"Service.All.Use",
"Service.Spaces.Use"
]
},
"description": "List of roles the person has in the organization; can be empty"
},
"reference": {
"type": "string",
"description": "Optional reference string, visible only to the organization admin"
}
},
"$schema": "http://json-schema.org/draft-04/schema#"
}Headers
Content-Type: application/json
Authorization: Bearer mnopqr.7890123.stuvwx
Location: /id/v3/organizations/n_gwumunrj77j-r0/members/533h18.ygguv_b_0Body
{
"uid": "533h18.ygguv_b_0",
"externalUid": "a03a45b7-2a14-c789-23a6-a9c6c8e42136",
"externalIdentityProvider": "https://login.microsoftonline.com/common/v2.0",
"name": "Horst Groby",
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"hasAvatar": true,
"createdAt": "2022-05-11T10:50:50Z",
"lastLoginAt": "2022-06-17T12:46:56Z",
"emails": [
{
"address": "bob@example.org",
"primary": true,
"verified": true,
"removeAt": "null"
}
],
"roles": [
"Organization.Admin"
],
"reference": "Hello, world!"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique ID of the person"
},
"externalUid": {
"type": "string",
"description": "Optional external UID, as defined by the external identity provider. `null` for local users."
},
"externalIdentityProvider": {
"type": "string",
"description": "Optional issuer-string of the identity provider that covers this person."
},
"name": {
"type": "string",
"description": "Name of person, if set."
},
"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."
},
"hasAvatar": {
"type": "boolean",
"description": "True if the person has an avatar."
},
"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"
},
"roles": {
"type": "array",
"items": {
"type": "string",
"enum": [
"Organization.Admin",
"Contract.Admin",
"Contract.Read",
"Service.Transfer.Use",
"Service.Transfer.Archive.CreateRoot",
"Service.Drive.CreateSpace",
"Service.All.Use",
"Service.Spaces.Use"
]
},
"description": "List of roles the person has in the organization; can be empty"
},
"reference": {
"type": "string",
"description": "Optional reference string, visible only to the organization admin."
}
},
"required": [
"uid",
"locale",
"timeZone",
"hasAvatar",
"createdAt",
"lastLoginAt",
"emails",
"roles"
]
}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 update the organization. Target person is not a member of this organization. Cannot drop own admin role.
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 roles of a memberPOST/id/v3/organizations/{uid}/members
An organization administrator can update the role-assignments of a person. The person has to be a member already.
-
It is perfectly fine to remove all roles from a person. The person still remains an organization member, but without any privileges.
-
An organization administrator can update their own role-assignments. However, they cannot drop their own
Organization.Adminrole (this must be done by a different organization administrator).
Since the organization membership changes, the backend blacklists all previous tokens of the person. Afterwards, the person must re-authenticate themselves. It also results in a PRIVILEGES_UPDATED SignalingEvent to that person.
If an organization administrator updates their own role-assignments, a new ID token issued as part of this request. The new token is delivered via the Authorization header.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"uid": "533h18.ygguv_b_0",
"externalUid": "a03a45b7-2a14-c789-23a6-a9c6c8e42136",
"externalIdentityProvider": "https://login.microsoftonline.com/common/v2.0",
"name": "Horst Groby",
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"hasAvatar": true,
"createdAt": "2022-05-11T10:50:50Z",
"lastLoginAt": "2022-06-17T12:46:56Z",
"emails": [
{
"address": "bob@example.org",
"primary": true,
"verified": true,
"removeAt": "null"
}
],
"roles": [
"Organization.Admin"
],
"reference": "Hello, world!"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"uid": {
"type": "string",
"description": "Unique ID of the person"
},
"externalUid": {
"type": "string",
"description": "Optional external UID, as defined by the external identity provider. `null` for local users."
},
"externalIdentityProvider": {
"type": "string",
"description": "Optional issuer-string of the identity provider that covers this person."
},
"name": {
"type": "string",
"description": "Name of person, if set."
},
"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."
},
"hasAvatar": {
"type": "boolean",
"description": "True if the person has an avatar."
},
"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"
},
"roles": {
"type": "array",
"items": {
"type": "string",
"enum": [
"Organization.Admin",
"Contract.Admin",
"Contract.Read",
"Service.Transfer.Use",
"Service.Transfer.Archive.CreateRoot",
"Service.Drive.CreateSpace",
"Service.All.Use",
"Service.Spaces.Use"
]
},
"description": "List of roles the person has in the organization; can be empty"
},
"reference": {
"type": "string",
"description": "Optional reference string, visible only to the organization admin."
}
},
"required": [
"uid",
"locale",
"timeZone",
"hasAvatar",
"createdAt",
"lastLoginAt",
"emails",
"roles"
]
}Insufficient authorization to fetch the membership.
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."
}
}
}
}
}Person or 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."
}
}
}
}
}Get memberGET/id/v3/organizations/{uid}/members/{personUid}
Fetches details of the membership.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
- personUid
string(required) Example: 533h18.ygguv_b_0The uid of the person
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Authorization: Bearer mnopqr.7890123.stuvwxInsufficient authorization to remove the membership. Unable to remove last organization admin.
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."
}
}
}
}
}Remove membershipDELETE/id/v3/organizations/{uid}/members/{personUid}?inform={inform}
Removes the person as a member of the organization. This deletes the account of the person and triggers the deletion of the person’s data in other backends. All ID tokens of the person are blacklisted.
If requested, an email is sent to the person, informing them of their account deletion.
An organization must always have at least one member with Organization.Admin role. Removing the “last administrator” is rejected.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
- personUid
string(required) Example: 533h18.ygguv_b_0The uid of the person
- inform
boolean(optional) Example: falseNotify the person of their removal
Invitation management ¶
An invitation allows a person to join an organization with a set of privileges. Since a person can only be member of one organization at a time, in order to accept an invitation, a person must first end their current membership.
A personalized invitation is addressed to an email address. It can only be accepted if it matches a verified email address of the person. Only one active invitation per email address is allowed. In order to change the invitation, it must be revoked and re-issued.
A person can only be invited if they are not yet a member of the organization.
A person can reject an invitation. This is visible in the status: rejected.
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"invitations": [
{
"invitee": "bob@example.org",
"roles": [
"Organization.Admin"
],
"reference": "Hello, world!",
"key": "u7u1kzz8hq",
"createdAt": "2022-05-11T10:50:50Z",
"status": "shared",
"inviterUid": "533h18.ygguv_b_0"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"invitations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"invitee": {
"type": "string",
"enum": [
"bob@example.org"
],
"description": "Set to the email address of the intended recipient."
},
"roles": {
"type": "array",
"items": {
"type": "string",
"enum": [
"Organization.Admin",
"Contract.Admin",
"Contract.Read",
"Service.Transfer.Use",
"Service.Transfer.Archive.CreateRoot",
"Service.Drive.CreateSpace",
"Service.All.Use",
"Service.Spaces.Use"
]
},
"description": "List of roles that the invitation grants."
},
"reference": {
"type": "string",
"enum": [
""
],
"description": "Internal reference text describing the invitation. Only visible to administrators."
},
"key": {
"type": "string",
"enum": [
"u7u1kzz8hq"
],
"description": "Identifies the invitation."
},
"createdAt": {
"type": "string",
"enum": [
"2022-05-11T10:50:50Z"
],
"description": "Timestamp when the invitation was initially created."
},
"status": {
"type": "string",
"enum": [
"shared",
"invited",
"accepted",
"rejected",
"assigned"
],
"description": "The current status of the invitation."
},
"inviterUid": {
"type": "string",
"enum": [
"533h18.ygguv_b_0"
],
"description": "Unique ID of the person that issued the invitation"
}
},
"required": [
"roles",
"key",
"createdAt",
"status"
],
"additionalProperties": false
},
"description": "List of invitations"
}
},
"required": [
"invitations"
]
}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."
}
}
}
}
}List all invitationsGET/id/v3/organizations/{uid}/invitations
Returns all invitations of the selected organization. An invitation that has been accepted is converted into a membership and won’t be shown here.
An invitation may reference the UID of the person that issued the invitation. If the inviter is removed later, the field is null.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Headers
Authorization: Bearer abcdef.123456.ghijklBody
{
"invitee": "bob@example.org",
"roles": [
"Organization.Admin"
],
"reference": "Hello, world!"
}Schema
{
"type": "object",
"properties": {
"invitee": {
"type": "string",
"description": "Set to the email address of the intended recipient."
},
"roles": {
"type": "array",
"items": {
"enum": [
"Organization.Admin",
"Contract.Admin",
"Contract.Read",
"Service.Transfer.Use",
"Service.Transfer.Archive.CreateRoot",
"Service.Drive.CreateSpace",
"Service.All.Use",
"Service.Spaces.Use"
]
},
"description": "List of roles that the invitation grants."
},
"reference": {
"type": "string",
"description": "Internal reference text describing the invitation. Only visible to administrators."
}
},
"required": [
"roles"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}Headers
Content-Type: application/json
Location: /id/v3/organizations/n_gwumunrj77j-r0/invitations/u7u1kzz8hqBody
{
"invitee": "bob@example.org",
"roles": [
"Organization.Admin"
],
"key": "u7u1kzz8hq",
"createdAt": "2022-05-11T10:50:50Z",
"status": "invited",
"inviterUid": "533h18.ygguv_b_0"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"invitee": {
"type": "string",
"description": "Set to the email address of the intended recipient."
},
"roles": {
"type": "array",
"description": "List of roles that the invitation grants."
},
"reference": {
"type": "string",
"description": "Internal reference text describing the invitation. Only visible to administrators."
},
"key": {
"type": "string",
"description": "Identifies the invitation."
},
"createdAt": {
"type": "string",
"description": "Timestamp when the invitation was initially created."
},
"status": {
"type": "string",
"description": "The current status of the invitation."
},
"inviterUid": {
"type": "string",
"description": "Unique ID of the person that issued the invitation"
}
},
"required": [
"roles",
"key",
"createdAt",
"status"
]
}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 issue an invitation.
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."
}
}
}
}
}Create a new invitationPOST/id/v3/organizations/{uid}/invitations
An organization administrator can invite a person to join the organization. If set, the contents of the invitee field must match a verified email address of the person in order for them to accept the invitation.
If the invitee field is set, the backend will issue a notification to the given email address. If it corresponds to a verified email address of a person, an INVITATION_ACTIVITY SignalingEvent is sent to that person as well.
It is perfectly fine to issue an invitation without roles. The person would then become a member of the organization without any privileges.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Headers
Authorization: Bearer abcdef.123456.ghijklHeaders
Content-Type: application/jsonBody
{
"invitee": "bob@example.org",
"roles": [
"Organization.Admin"
],
"key": "u7u1kzz8hq",
"createdAt": "2022-05-11T10:50:50Z",
"status": "invited",
"inviterUid": "533h18.ygguv_b_0"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"invitee": {
"type": "string",
"description": "Set to the email address of the intended recipient."
},
"roles": {
"type": "array",
"description": "List of roles that the invitation grants."
},
"reference": {
"type": "string",
"description": "Internal reference text describing the invitation. Only visible to administrators."
},
"key": {
"type": "string",
"description": "Identifies the invitation."
},
"createdAt": {
"type": "string",
"description": "Timestamp when the invitation was initially created."
},
"status": {
"type": "string",
"description": "The current status of the invitation."
},
"inviterUid": {
"type": "string",
"description": "Unique ID of the person that issued the invitation"
}
},
"required": [
"roles",
"key",
"createdAt",
"status"
]
}Insufficient authorization to fetch the invitation.
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."
}
}
}
}
}Person or 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."
}
}
}
}
}Get invitationGET/id/v3/organizations/{uid}/invitations/{key}
Fetches details of the invitation.
An invitation may reference the UID of the person that issued the invitation. If the inviter is removed later, the field is null.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
- key
string(required) Example: u7u1kzz8hqThe invitation key
Headers
Authorization: Bearer abcdef.123456.ghijklInsufficient authorization to remove the invitation.
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."
}
}
}
}
}Revoke invitationDELETE/id/v3/organizations/{uid}/invitations/{key}
Removes the invitation.
If the invitee field is set, the backend will issue an INVITATION_ACTIVITY SignalingEvent to that person.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within the organization.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
- key
string(required) Example: u7u1kzz8hqThe invitation key
Data migration ¶
These endpoints are intended for migration from an existing system to Skalio ID.
Headers
Authorization: Bearer abcdef.123456.ghijklThe operation was successful.
Headers
Content-Type: application/json
Location: /id/v3/organizations/n_gwumunrj77j-r0Body
{
"mfaRequired": false,
"uid": "n_gwumunrj77j-r0",
"externalUid": "e607e95f-ad60-1c8e-a888-34a4ae2b8418",
"hasAvatar": false,
"profile": {
"name": "Example Inc",
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"legalNoticeUrl": "https://www.example.test/imprint/",
"privacyPolicyUrl": "https://www.example.test/privacy/",
"hostname": "teambeam.example.test",
"inactiveHostnames": [
"old.example.test"
]
},
"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"
}
],
"memberCount": 1,
"memberLimit": 5
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"mfaRequired": {
"type": "boolean",
"description": "Shows if the organization requires members to use multi-factor authentication."
},
"uid": {
"type": "string",
"description": "Unique ID of the organization. Readonly."
},
"externalUid": {
"type": "string",
"description": "Optional external UID. Typically a MS Entra tenant ID."
},
"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."
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The default locale of the organization."
},
"timeZone": {
"type": "string",
"description": "The default time zone of the organization."
},
"globalSignature": {
"type": "string",
"description": "A corporate email signature."
},
"legalNoticeUrl": {
"type": "string",
"description": "A URL pointing to a legal notice document."
},
"privacyPolicyUrl": {
"type": "string",
"description": "A URL pointing to a privacy policy document."
},
"hostname": {
"type": "string",
"description": "The active hostname where the service for the organization is hosted."
},
"inactiveHostnames": {
"type": "array",
"description": "Non-null, possibly empty array of no-longer-active hostnames of the organization."
}
},
"required": [
"name",
"locale",
"timeZone",
"inactiveHostnames"
],
"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"
},
"memberCount": {
"type": "number",
"description": "Number of members"
},
"memberLimit": {
"type": "number",
"description": "Max number of members"
}
},
"required": [
"mfaRequired",
"uid",
"hasAvatar",
"profile",
"subscriptions",
"memberCount",
"memberLimit"
]
}Create organizationPOST/id/v3/organizations
This endpoint is used for migration of customers only.
Creates a new organization, organization profile and hostname. The organization has no members or subscriptions. A customer account at the subscription management system is created and linked to the organization.
A random active hostname is created, if the imported profile did not specify one.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Cluster.Admin role.
Headers
Authorization: Bearer abcdef.123456.ghijklThe operation was successful.
Headers
Content-Type: application/jsonBody
{
"mfaRequired": false,
"uid": "n_gwumunrj77j-r0",
"externalUid": "e607e95f-ad60-1c8e-a888-34a4ae2b8418",
"hasAvatar": false,
"profile": {
"name": "Example Inc",
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"legalNoticeUrl": "https://www.example.test/imprint/",
"privacyPolicyUrl": "https://www.example.test/privacy/",
"hostname": "teambeam.example.test",
"inactiveHostnames": [
"old.example.test"
]
},
"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"
}
],
"memberCount": 1,
"memberLimit": 5
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"mfaRequired": {
"type": "boolean",
"description": "Shows if the organization requires members to use multi-factor authentication."
},
"uid": {
"type": "string",
"description": "Unique ID of the organization. Readonly."
},
"externalUid": {
"type": "string",
"description": "Optional external UID. Typically a MS Entra tenant ID."
},
"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."
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The default locale of the organization."
},
"timeZone": {
"type": "string",
"description": "The default time zone of the organization."
},
"globalSignature": {
"type": "string",
"description": "A corporate email signature."
},
"legalNoticeUrl": {
"type": "string",
"description": "A URL pointing to a legal notice document."
},
"privacyPolicyUrl": {
"type": "string",
"description": "A URL pointing to a privacy policy document."
},
"hostname": {
"type": "string",
"description": "The active hostname where the service for the organization is hosted."
},
"inactiveHostnames": {
"type": "array",
"description": "Non-null, possibly empty array of no-longer-active hostnames of the organization."
}
},
"required": [
"name",
"locale",
"timeZone",
"inactiveHostnames"
],
"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"
},
"memberCount": {
"type": "number",
"description": "Number of members"
},
"memberLimit": {
"type": "number",
"description": "Max number of members"
}
},
"required": [
"mfaRequired",
"uid",
"hasAvatar",
"profile",
"subscriptions",
"memberCount",
"memberLimit"
]
}Import organization profilePUT/id/v3/organizations/{uid}/import/person
This endpoint is used for migration of customers only.
Updates an existing organization, overwriting organization profile and hostnames. Does not change memberships or subscriptions.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Cluster.Admin role.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Headers
Authorization: Bearer abcdef.123456.ghijklBody
{
"email": "bob@example.org",
"name": "Bob",
"passwordHash": "$2a$12$iFJH7Yxc7qfz5QLQ7W4.m.9swQZN9ty7QMv8G2OsoPjy10GBemaPm",
"locale": "de_DE",
"timeZone": "Europe/Berlin",
"roles": [
"Organization.Admin"
]
}Schema
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address of the person"
},
"name": {
"type": "string",
"description": "The name of the person"
},
"passwordHash": {
"type": "string",
"description": "Salted bcrypt hash of the persons password"
},
"locale": {
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP",
"de_DE"
],
"description": "The locale of the person"
},
"timeZone": {
"type": "string",
"description": "The timezone of the person"
},
"roles": {
"type": "array",
"items": {
"enum": [
"Organization.Admin",
"Contract.Admin",
"Contract.Read",
"Service.Transfer.Use",
"Service.Transfer.Archive.CreateRoot",
"Service.Drive.CreateSpace",
"Service.All.Use",
"Service.Spaces.Use"
]
},
"description": "Set of roles of the person"
}
},
"required": [
"email",
"passwordHash",
"locale",
"timeZone"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}Headers
Content-Type: application/json
Location: /id/v3/public/profile/533h18.ygguv_b_0Body
{
"uid": "533h18.ygguv_b_0",
"name": "Horst Groby",
"email": "alice@example.net",
"hasAvatar": true,
"fingerprint": [
{
"name": "christmasTree",
"codePoint": 127876,
"title": "christmas tree"
}
],
"locale": "de_DE",
"timeZone": "Europe/Berlin"
}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"
},
"locale": {
"type": "string",
"enum": [
"de_DE",
"en_US",
"fr_FR",
"ru_RU",
"ko_KR",
"zh_CN",
"zh_TW",
"ja_JP"
],
"description": "The locale of the person"
},
"timeZone": {
"type": "string",
"description": "The person's timezone"
}
},
"required": [
"uid",
"hasAvatar",
"fingerprint",
"locale",
"timeZone"
]
}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 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."
}
}
}
}
}Import person into organizationPOST/id/v3/organizations/{uid}/import/person
This endpoint is used for migration of customers only.
This imports a person into Skalio ID and grants them membership in the organization, assigning the requested privileges. The person is matched by email address: if a person is not found, it is being created.
-
find person by email; create it, if not found:
- create person
- create email address of person
-
if a password hash was provided, create
bcryptauthenticator for the person -
assign person to organization, if not already a member
-
set roles of organization membership
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Cluster.Admin role.
- uid
string(required) Example: n_gwumunrj77j-r0The uid of the organization
Products & Subscriptions ¶
Products ¶
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/v3/products?domain={domain}
Returns a list of products registered in Skalio ID.
Requests must be authenticated with an access token.
- domain
ProductDomain(optional) Example: skpAn optional filter to limit listing of products
Subscriptions ¶
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/v3/subscriptions/stripe/checkout/{domain}/{productId}
In order to purchase the initial subscription of a product from a specific domain, a person can start a checkout-session with Stripe. Within this checkout session, the customer can purchase a subscription to a product. This creates an organization matching the Stripe “customer”, assigning the person as organization admin.
Since this triggers the initial shopping experience, this resource is limited to persons without an organization.
The response contains a URL to the checkout page hosted at Stripe. It is valid for a short time only; check the expiration timestamp.
Requests must be authenticated with an access token.
- domain
ProductDomain(required) Example: skpThe domain of the product
- productId
string(required) Example: proThe 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/v3/subscriptions/stripe/portal
Once an organization has subscribed to a product, the subscription can be managed in the Stripe Customer Portal. A session can be requested here. The expiresAt field of the session is always null.
Requests must be authenticated with an access token.
To access this API endpoint, the principal must have the Organization.Admin role within the organization.
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/v3/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 ¶
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/v3/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.
Requests must be authenticated with a UID token.
-
emailmust be provided when submitting support requests. -
starsmust 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/v3/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
SCIM ¶
The System for Cross-domain Identity Management is described in detail here.
The documentation here is only meant to demonstrate the base URL of the SCIM service and the available endpoints. The RFC has details how to use the endpoints.
SCIM ¶
Headers
Content-Type: application/jsonSchemaGET/id/v3/scim/Schemas
Implements the Schemas-endpoint as per the RFC.
Headers
Content-Type: application/jsonUsersGET/id/v3/scim/Users
Implements the Users-endpoint as per the RFC.
Generated by aglio on 19 Sep 2024