Issuing credentials from your system
Integration through the REST interface: access, process, error cases and revocation, with examples you can follow.
When credentials are created regularly, when someone joins or for each approved parking permit, nobody should have to issue them by hand. Your HR, CRM or specialist system takes this over through VeriGate’s REST interface.
What the interface can do
- Query the details of a credential type: which exist and which are mandatory.
- Create an offer: VeriGate responds with a link that the person opens with the swiyu Wallet.
- Query the status of an offer: open, collected, expired.
- List issued credentials, suspend them, reinstate them and revoke them.
Everything the console does for issuing is therefore also available to your system. Design stays in the console.
Access: one per credential type
Your system receives technical access under OAuth 2.0 (Client Credentials). It applies to exactly one credential type of your organisation. An HR system issuing staff IDs therefore cannot issue access authorisations, not even by mistake.
Every call is logged with the access that made it. The values of the details do not appear in the log.
The process in four calls
The examples use the organisation musterwil and the credential type parking-permit. You receive your own identifiers with the access.
1. Get a token
POST https://id.verigate.ch/realms/verigate-providers/protocol/openid-connect/token
grant_type=client_credentials
client_id=…
client_secret=…
2. Create an offer
POST https://api.verigate.ch/api/provider/v1/tenants/musterwil/credential-types/parking-permit/offers
Authorization: Bearer …
Idempotency-Key: 4711
{ "claims": { "given_name": "Marco",
"family_name": "Rossi",
"zone": "B",
"number_plate": "BE 482 117",
"valid_until": "2027-12-31" } }
The response contains the offer’s identifier, the link for the wallet and how long the offer is valid:
{ "requestId": "8f3c…",
"state": "OFFERED",
"offerDeeplink": "swiyu://…",
"expiresAt": "2026-10-28T09:15:00Z" }
You send the link by email or show it as a QR code in your own portal.
3. Query the status
GET …/credential-types/parking-permit/offers/8f3c…
OFFERED means: not collected yet. With ISSUED, the credential is in the wallet, and the response gives its identifier credentialRef. EXPIRED and FAILED close the offer; a new one is possible at any time.
4. Revoke when it no longer applies
POST …/credential-types/parking-permit/credentials/{credentialRef}/state
{ "state": "REVOKED" }
SUSPENDED suspends temporarily, VALID reinstates a suspended credential. A revoked credential stays revoked.
Built for retries
Networks fail, calls time out, and your system tries again. That is why creating an offer requires an Idempotency-Key, for example the application number. If the same key arrives twice, your system gets back the offer already created instead of generating a second one. If the same key arrives with different details, VeriGate rejects it with 409, rather than silently discarding one of the two versions.
Each access has a quota: 60 write and 600 read calls per minute. If it is exceeded, VeriGate responds with 429 and says in Retry-After when to continue.
Description and testing
The interface is fully described in OpenAPI. Your software partner can generate code from it and develop against a test organisation before real credentials are issued.
What comes next
- Issuing, status, revocationEverything in this article.Available
- Starting checks and processes from your systemFor example “Verify e-ID, then issue” from your portal, without the console.Planned