API-referens

TIC Identity API är ett RESTful API som använder JSON för både request och response. Alla anrop kräver autentisering via API-nyckel.

Bas-URL

https://id.tic.io/api/v1

Autentisering

Alla API-anrop kräver en giltig API-nyckel som skickas i X-Api-Key-headern.

curl -H "X-Api-Key: YOUR_API_KEY" \
     https://id.tic.io/api/v1/usage

Skydda din API-nyckel

Exponera aldrig din API-nyckel i klientkod. Alla API-anrop ska göras från din backend.

Endpoints

Autentisering

POST /api/v1/auth/{provider}/start

Startar en ny autentiseringssession.

POST /api/v1/auth/{sessionId}/poll

Pollar BankID och returnerar aktuell status. Använd denna för polling.

GET /api/v1/auth/{sessionId}/collect

Hämtar cachad sessionsdata. Kontaktar inte BankID — använd efter webhook eller callback.

DELETE /api/v1/auth/{sessionId}

Avbryter en pågående session.

Signering

POST /api/v1/auth/{provider}/sign

Startar en ny signeringssession.

GET /api/v1/auth/{sessionId}/collect

Hämtar cachad sessionsdata för en slutförd signeringssession.

Se fullständig dokumentation för autentisering →

Se fullständig dokumentation för signering →

Svarsformat

Alla svar returneras i JSON-format. Lyckade anrop returnerar HTTP 200 med data. Fel returnerar lämplig HTTP-statuskod med ett felobjekt.

Lyckat svar

{
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider": "bankid",
  "orderRef": "131daac9-16c6-4618-beb0-365768f37288",
  "autoStartToken": "7c40b5c9-fa74-49cf-b98c-bfe651f9a7c6",
  "qrStartToken": "67df3917-fa0d-44e5-b327-edcc928297f8",
  "qrStartSecret": "d28db9a7-4cde-429e-a983-359be676944c",
  "subscriptionToken": "sub_abc123...",
  "sessionExpiresAt": "2026-01-15T14:35:00Z",
  "endUserIp": "192.168.1.1"
}

Fält	Beskrivning
`sessionId`	Unikt sessions-ID för att identifiera autentiseringen
`orderRef`	BankID:s orderreferens för aktuell order
`autoStartToken`	Token för att öppna BankID-appen på samma enhet
`qrStartToken`	Token för att generera QR-kod (annan enhet)
`qrStartSecret`	Hemlighet för att beräkna animerad QR-kod
`subscriptionToken`	Engångstoken för SignalR-prenumeration (giltig 5 min)
`sessionExpiresAt`	Tidpunkt när sessionen går ut
`endUserIp`	IP-adressen som startade sessionen (för säkerhetsverifiering)

Felsvar

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: endUserIp",
    "details": {
      "parameter": "endUserIp",
      "expected": "string (IP address)"
    }
  }
}

Rate limits

API:et har följande rate limits för att säkerställa stabil drift:

Limit	Värde	Beskrivning
Requests per minut	240	Per API-nyckel
Requests per timme	3000	Per API-nyckel
Requests per dag	10000	Per API-nyckel

Rate limit-status returneras i response headers:

X-RateLimit-Limit-Minute: 240
X-RateLimit-Remaining-Minute: 238
X-RateLimit-Limit-Hour: 3000
X-RateLimit-Remaining-Hour: 2987

Rate limits för autentisering

Autentiseringsendpoints (/api/v1/auth/*) har ytterligare IP-baserad rate limiting som skydd mot brute force-attacker:

Limit	Värde	Beskrivning
Försök per IP	50 / 15 min	Max antal autentiseringsförsök per IP-adress
Första blockeringen	15 minuter	Vid första överträdelsen
Andra blockeringen	1 timme	Vid andra överträdelsen
Tredje+ blockeringen	24 timmar	Vid upprepade överträdelser

Vid blockering returneras HTTP 429 med Retry-After header som anger antal sekunder tills blockeringen upphör.

OBS: Om flera användare delar samma publika IP-adress (t.ex. i ett kontor) delar de också rate limit. Gränsen på 50 försök per 15 minuter är satt för att tillåta normalt användande i kontorsmiljöer.

Felkoder

Se felkodsreferensen för en komplett lista över alla felkoder och hur du hanterar dem.