Wissen · Technik

Nachweise aus Ihrem System ausstellen

Die Anbindung über die REST-Schnittstelle: Zugang, Ablauf, Fehlerfälle und Widerruf, mit Beispielen zum Nachbauen.

3 Min. Lesezeit·Für Ihre IT und Ihren Softwarepartner

Wenn Nachweise regelmässig entstehen, beim Eintritt einer Mitarbeiterin oder bei jeder bewilligten Parkkarte, soll niemand sie von Hand ausstellen. Ihr HR-, CRM- oder Fachsystem übernimmt das über die REST-Schnittstelle von VeriGate.

Was die Schnittstelle kann

Angaben eines Nachweistyps abfragen: welche es gibt und welche Pflicht sind.
Ein Angebot erstellen: VeriGate antwortet mit einem Link, den die Person mit der swiyu Wallet öffnet.
Den Stand eines Angebots abfragen: offen, abgeholt, abgelaufen.
Ausgestellte Nachweise auflisten, sperren, wieder freigeben und widerrufen.

Alles, was die Konsole beim Ausstellen tut, steht damit auch Ihrem System zur Verfügung. Die Gestaltung bleibt in der Konsole.

Der Zugang: einer pro Nachweistyp

Ihr System erhält einen technischen Zugang nach OAuth 2.0 (Client Credentials). Er gilt für genau einen Nachweistyp Ihrer Organisation. Ein HR-System, das Mitarbeiterausweise ausstellt, kann also keine Zutrittsberechtigungen ausstellen, auch nicht durch einen Fehler.

Jeder Aufruf wird mit dem Zugang protokolliert, der ihn gemacht hat. Die Werte der Angaben stehen nicht im Protokoll.

Der Ablauf in vier Aufrufen

Die Beispiele verwenden die Organisation musterwil und den Nachweistyp parkkarte. Ihre eigenen Kennungen erhalten Sie mit dem Zugang.

1. Token holen

POST https://id.verigate.ch/realms/verigate-providers/protocol/openid-connect/token
grant_type=client_credentials
client_id=…
client_secret=…

2. Angebot erstellen

POST https://api.verigate.ch/api/provider/v1/tenants/musterwil/credential-types/parkkarte/offers
Authorization: Bearer …
Idempotency-Key: 4711

{ "claims": { "given_name": "Marco",
              "family_name": "Rossi",
              "zone": "B",
              "kontrollschild": "BE 482 117",
              "valid_until": "2027-12-31" } }

Die Antwort enthält die Kennung des Angebots, den Link für die Wallet und wie lange das Angebot gilt:

{ "requestId": "8f3c…",
  "state": "OFFERED",
  "offerDeeplink": "swiyu://…",
  "expiresAt": "2026-10-28T09:15:00Z" }

Den Link schicken Sie per E-Mail oder zeigen ihn als QR-Code in Ihrem eigenen Portal.

3. Stand abfragen

GET …/credential-types/parkkarte/offers/8f3c…

OFFERED heisst: noch nicht abgeholt. Bei ISSUED ist der Nachweis in der Wallet, und die Antwort nennt seine Kennung credentialRef. EXPIRED und FAILED schliessen das Angebot ab; ein neues ist jederzeit möglich.

4. Widerrufen, wenn er nicht mehr gilt

POST …/credential-types/parkkarte/credentials/{credentialRef}/state
{ "state": "REVOKED" }

SUSPENDED sperrt vorübergehend, VALID gibt einen gesperrten Nachweis wieder frei. Ein widerrufener Nachweis bleibt widerrufen.

Gebaut für Wiederholungen

Netzwerke fallen aus, Aufrufe laufen in Zeitüberschreitungen, und Ihr System versucht es erneut. Deshalb verlangt das Erstellen eines Angebots einen Idempotency-Key, zum Beispiel die Nummer des Gesuchs. Kommt derselbe Schlüssel zweimal, erhält Ihr System das bereits erstellte Angebot zurück, statt ein zweites zu erzeugen. Kommt derselbe Schlüssel mit anderen Angaben, lehnt VeriGate mit 409 ab, statt eine der beiden Fassungen stillschweigend zu verwerfen.

Jeder Zugang hat ein Kontingent: 60 schreibende und 600 lesende Aufrufe pro Minute. Wird es überschritten, antwortet VeriGate mit 429 und sagt in Retry-After, wann es weitergeht.

Beschreibung und Test

Die Schnittstelle ist vollständig in OpenAPI beschrieben. Ihr Softwarepartner kann daraus Code erzeugen und gegen eine Testorganisation entwickeln, bevor echte Nachweise ausgestellt werden.

Was als Nächstes kommt

Ausstellen, Stand, WiderrufAlles in diesem Beitrag.
Verfügbar
Prüfungen und Abläufe aus Ihrem System startenEtwa «e-ID prüfen, dann ausstellen» aus Ihrem Portal heraus, ohne Konsole.
Geplant

Anbindung besprechen