Getting started

This guide takes you from nothing to your first API call. The API reference lists every operation the API offers to an integrating platform.

1. Get a service account

An administrator of your eimHub tenant creates a service account for your platform in the eimHub console (Users & roles → Service accounts). They choose:

• the sub-tenant the account works in;
• the roles it holds — the Integrator role is meant for platforms: it manages devices, eUICCs, profiles and operations, bulk operations included, without user administration or usage data. Each operation in the API reference names the roles that may call it in its Roles line (see Roles);
• how it authenticates: a client secret, or a key pair whose private key never leaves your system (see Authentication).

You receive a client id, for example sa-acme-erp, and — for a client secret — the secret, shown once.

2. Obtain an access token

Tokens come from the identity provider's token endpoint with the OAuth 2.0 client credentials grant. The console's API access panel of your service account shows the token endpoint of your environment; the examples here use id.eimhub.example.

TOKEN=$(curl -s https://id.eimhub.example/realms/eimhub/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id=sa-acme-erp \
  -d client_secret="$CLIENT_SECRET" \
  | jq -r .access_token)

The access token is valid for 15 minutes. Reuse it until it expires; do not request one per call (see Authentication).

3. Make your first call

Every call carries the token as a bearer token. GET /api/v1/me tells you who you are, which tenant you act on and which roles you hold:

curl -s https://app.eimhub.example/api/v1/me -H "Authorization: Bearer $TOKEN"

Then list the eUICCs you can see:

curl -s "https://app.eimhub.example/api/v1/euiccs?limit=10" -H "Authorization: Bearer $TOKEN"

Next steps

• Conventions: idempotency, pagination, filtering, errors and rate limits.
• Operations: how a command reaches a card and how you learn its result.
• Webhooks: be told instead of polling.