Authentication

The eMSP API authenticates with OAuth2 client credentials. You exchange a client ID and secret for a short-lived access token, then send that token as a bearer token on every request. This is different from the rest of the Spirii API, which uses a long-lived API key. If you’re integrating against those endpoints, see Authentication instead.

How access is structured

Four things sit between your company and an endpoint. Your organisation is your company as Spirii knows it. Inside it, a workspace groups credentials; on the eMSP API a workspace is a tenant, so the workspace your credential belongs to decides whose networks, locations and webhooks you’re working with. A credential is one OAuth2 client: a client ID and a secret. The scopes attached to that credential set the capabilities it can ask for. You never pass an organisation, workspace or tenant ID in a request. All three travel inside the access token, and Spirii resolves them from it.

Get your credentials

Spirii provisions credentials during onboarding. Your Spirii contact sends you a client ID, a client secret, and the list of scopes attached to the credential. Store the secret in a secret manager or an environment variable, never in source control. The security best practices for API keys apply here unchanged. When your integration grows into a capability the credential doesn’t cover, ask Spirii to attach the scope. That’s a grant against your existing credential, not a new credential and not a code change on your side.

Get an access token

Post your credentials to the token endpoint of Spirii’s public-api realm, naming the scopes you want the token to carry:

curl -X POST 'https://auth.spirii.dk/realms/public-api/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d "client_id=$SPIRII_CLIENT_ID" \
  -d "client_secret=$SPIRII_CLIENT_SECRET" \
  --data-urlencode 'scope=emsp:networks:read emsp:locations:read'

Scope values are space-separated, so they have to be URL-encoded. With curl that means --data-urlencode rather than -d. The response carries four fields worth reading:

Field	What it’s for
`access_token`	The token you send as a bearer token
`expires_in`	Seconds until the token expires. Access tokens live for 300 seconds
`token_type`	Always `Bearer`
`scope`	The scopes the token actually carries. Check this matches what you asked for

A token is good for five minutes. Cache it and fetch a new one shortly before it expires. Requesting a token per API call works, but it adds a round trip to every request for no benefit.

Scopes

A scope attached to your credential makes it allowed to request that capability. It does not put the capability in every token. The token carries a scope only when you name it in the scope parameter. Two things follow from that, and both look like a broken integration when you meet them for the first time.

Omit the scope parameter and the token request still succeeds. You get a valid token carrying none of your capabilities, and every eMSP endpoint answers 403. Request a scope that isn’t attached to your credential and the whole token request fails with invalid_scope, so a single typo costs you the token rather than that one scope.

These are the scopes available across the eMSP API:

API	Scope	Grants
Tenants	`emsp:tenants:read`	View tenant profile, EMP identities, and webhooks
Tenants	`emsp:tenants:write`	Manage tenant profile, EMP identities, and webhooks
Networks	`emsp:networks:read`	View network and access control configuration
Networks	`emsp:networks:write`	Create, update and delete SUB networks, and manage access rules
Networks	`emsp:networks:publish`	Publish and drain networks
Networks	`emsp:networks:subscribe`	Attach to another tenant’s published base network as a consumer
Locations	`emsp:locations:read`	Search and view locations, EVSEs and connectors
Webhooks	`emsp:webhooks:read`	View webhook subscriptions and delivery history
Webhooks	`emsp:webhooks:write`	Create, update, pause and delete webhook subscriptions

Ask for the scopes a given token needs rather than everything attached to the credential. A token minted for a nightly location sync has no reason to carry emsp:networks:publish, and keeping it out means a leaked token can’t be used to publish anything. Changing what’s attached to a credential doesn’t reach tokens already issued. After Spirii attaches a scope, request a new token to pick it up.

Authorize a request

Send the access token in the Authorization header, prefixed with Bearer:

curl 'https://api.spirii.com/emsp/v1/locations' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Every eMSP endpoint sits under https://api.spirii.com/emsp/v1.

What’s in the token

The access token is a signed JWT issued by https://auth.spirii.dk/realms/public-api using RS256. Decode it and you’ll find the claims Spirii uses to identify you:

Claim	What it holds
`azp`	Your client ID
`organisation_id`	The organisation the credential belongs to
`workspace_id`	The workspace, which is your eMSP tenant
`credential_id`	The credential itself, useful when you hold several
`scope`	The granted scopes, space-separated
`exp`	Expiry, as a Unix timestamp

Reading these claims helps when you’re working out why a call was refused. Spirii verifies the token and derives your identity from it on every request, so treat the claims as diagnostic information rather than something your own code makes access decisions from. Alongside your scopes, scope also carries Keycloak’s built-in defaults such as email and profile. They grant nothing on the eMSP API and are safe to ignore.

Errors

Response	Returned by	Cause
`invalid_client`	Token endpoint	Wrong client ID or secret, or the credential has been disabled
`invalid_scope`	Token endpoint	A requested scope isn’t attached to the credential, or is misspelled
`401` Unauthorized	eMSP API	The `Authorization` header is missing or malformed, or the token has expired or wasn’t issued by Spirii
`403` Forbidden	eMSP API	The token is valid but carries no scope covering this endpoint. Request a new token naming the scope you need
`403` Forbidden	eMSP API	The request presented an `x-spirii-*` header. Spirii sets those from your token; sending them yourself is rejected at the edge

Rotate and revoke

Ask Spirii to rotate the secret and you get a new one immediately; the old secret stops working for new token requests at the same moment. Tokens already issued are a different matter. A token stays valid for its full 300 seconds, and Spirii caches the result of verifying it for up to 300 seconds more, so a credential can keep working for roughly ten minutes after it’s rotated or disabled. Neither action is an instant kill switch; plan rotations and revocations around that window. To rotate without downtime: take the new secret, fetch a token with it to confirm it works, roll it into your integration, and drop the old one.

API overview

The four Spirii APIs, their path prefixes, and where to start.

Errors

The status codes the API returns and how to handle them.

Rate limits

The request limits and how to stay under them.

Get started

Spirii API

EMSP API

Billing API

Energy Management API

Legacy API

Authentication

How access is structured

Get your credentials

Get an access token

Scopes

Authorize a request

What’s in the token

Errors

Rotate and revoke

API overview

Errors

Rate limits

​How access is structured

​Get your credentials

​Get an access token

​Scopes

​Authorize a request

​What’s in the token

​Errors

​Rotate and revoke

​Related

API overview

Errors

Rate limits

How access is structured

Get your credentials

Get an access token

Scopes

Authorize a request

What’s in the token

Errors

Rotate and revoke

Related