Authorization

Every Public API request is authenticated with an API key and authorized against the back-office role that key carries.

Obtaining a key

Ask your Solidstudio contact for a key. Name it after the integration (for example erp-sync), so its requests can be told apart from other integrations'.

Sending the key

Send the key as the raw value of the Authorization header, with no Bearer prefix:

curl -s \
  -H "Authorization: $API_KEY" \
  "https://<host>/backoffice/sessions?page=1&size=10"

What a key can do

A valid API key authenticates as a SUPER_ADMIN. Every back-office endpoint declares the roles it accepts, and SUPER_ADMIN is accepted on all of them. So one key can read and change everything the EMSP Admin Panel can:

flowchart LR
    K["API key<br/>Authorization: &lt;key&gt;"] -->|authenticates as| R[SUPER_ADMIN]
    R -->|checked per endpoint| E["Back-office endpoint<br/>@PreAuthorize(roles)"]

Authentication failures

Both use the standard error body:

{ "code": "UNAUTHORIZED", "message": "Request is unauthorized" }

See Pagination, filtering & errors for the full error model.

Key lifecycle

• A key has no expiry date. It stays valid until Solidstudio revokes it.
• To rotate a key, ask for a new one, deploy it, then ask for the old one to be revoked. Both keys work at the same time until the old one is revoked.
• Revoked keys return 401 immediately.

Security recommendations

• Call the API host-to-host only. Never embed a key in a mobile app, browser code or a public repository.
• Use one key per integration so you can rotate and revoke keys independently, and so actions are attributed to the right system.
• Store keys in a secrets manager. Because every key is a SUPER_ADMIN credential, a leaked key gives full back-office access until it is revoked.
• If you suspect a key has leaked, ask for it to be revoked at once.

Related

• Getting started: base URL, quick start, resource catalog
• Pagination, filtering & errors: error model