API
Issue badges programmatically with a bearer token. Enterprise plan.
Enterprise only
API keys can be created only on the Enterprise plan; on other plans the API access panel in Settings shows an upgrade notice instead. A key whose organization later leaves Enterprise answers 403 plan_required. There is no self-serve sandbox or test key. To try the API before buying, ask us through the contact form: we can switch on a 14-day trial of the Enterprise plan for your organization, with no charge and no card. We set it up by hand, so it is not instant, and when the 14 days end the organization goes back to the plan it was on. Otherwise the lowest-cost way in is the Enterprise plan on monthly billing, which can be cancelled so it does not renew; the month is charged in full and the unused part is not refunded. See Plans and billing.
Getting a key
Create one under Settings → API access. Keys are prefixed ik_ and are shown once, at creation — we store only a hash, so we can't show it again. If it's lost, revoke it and make a new one. Several keys can be active at once, so to rotate without downtime, create a second key, switch your system to it, then revoke the first.
A typical integration. There is no ready-made connector for a learning management system, a student information system or a registration system. Your own system calls POST /api/v1/issue when a person completes a course, with external_id set to your own record id (an enrollment id, for example) so a retry never issues twice. That needs a key with Read and issue; revoking and restoring need Full access.
Pass it as a bearer token on every request. Plan limits, the duplicate-award guard, and pathway auto-awards apply as they do in the dashboard.
Key permissions
When you create a key you choose what it may do, which part of the organization it covers, and when it expires. The key itself, the rate limit, the plan and the account status are checked first; after those, a request that needs a permission the key lacks gets 403 insufficient_scope, and required_scope names it. Keys created before permissions existed have full access.
| Access | Allows |
|---|---|
read | GET /api/v1/badges, GET /api/v1/awards, GET /api/v1/awards/{id} and POST /api/v1/awards/search. |
issue | POST /api/v1/issue. |
revoke | POST /api/v1/awards/{id}/revoke and /restore. |
The create form offers three choices: Read only (read), Read and issue (read, issue), and Full access (all three, the default). A key limited to issue alone can't be created, so an integration that issues also needs read to list its badges.
Sub-organization keys. A key can be limited to one sub-organization; the default is the whole organization. Such a key sees and acts on only that sub-organization's badges and the awards of those badges. Anything else, such as another sub-organization's badge or award, answers 404 (badge_not_found or award_not_found) exactly as if it did not exist. If a badge is moved to another sub-organization, its awards move with it. A sub-organization can't be removed while active keys are limited to it: revoke them first, so a key never becomes organization-wide. Two things still reach across the organization: an external_id or Idempotency-Key must be unique in the whole organization, so a value already used by another sub-organization is refused with 409 idempotency_conflict; and if an admin has set up a pathway, issuing a badge can complete it and award that pathway's badge even when it sits in another sub-organization. An admin who is assigned to one sub-organization can create and revoke only keys limited to it.
Expiry. A key can expire after 30 days, 90 days, or 1 year, or never. An expired key is refused like a revoked one: 401 invalid_token. Create a new key to replace it; keys can't be extended.
List your badges
GET /api/v1/badges
curl "https://incredify.net/api/v1/badges?limit=50" \
-H "Authorization: Bearer ik_your_key"Badges come newest first. limit is 1 to 200 (default 50). When more remain, the response has a next_cursor; pass it back as cursor to get the next page. next_cursor is null on the last page. A bad limit or cursor returns 400 invalid_request. Each badge has id, name, description, archived, draft, sub_organization_id (or null), image_url (or null), folder (the name of the folder the badge is filed in, or null), default_validity_months (how many months awards of this badge last by default, 1 to 120, or null when they do not expire), and created_at. Requires read.
Issue a badge
POST /api/v1/issue
curl -X POST https://incredify.net/api/v1/issue \
-H "Authorization: Bearer ik_your_key" \
-H "Content-Type: application/json" \
-d '{
"badge_id": "<badge uuid>",
"recipient": { "email": "earner@example.edu", "name": "Jane Earner" }
}'
# 201 -> { "assertion_id": "...", "expires_at": null, "claim_url": "...", "verify_url": "..." }Optional fields: notify (boolean, default true) controls whether the recipient is emailed, and evidence accepts an array of up to 10 items with url, name, description, narrative, genre, and audience. File uploads aren't available over the API — attach files through single issuance in the dashboard.
Expiry dates
expires_at is optional and has three states. Omitted: the badge's default validity applies (issue date plus default_validity_months calendar months, clamped to the end of the month), or no expiry if the badge has none. `null`: this award does not expire, even if the badge has a default. A date or timestamp: "2027-06-30", or a full ISO 8601 timestamp with an offset, which is read as its UTC date. The award is valid through that day, and is stored and signed as 23:59:59 UTC on it. The date must be later than today (UTC) and no more than 50 years ahead; anything else returns 400 invalid_expires_at and nothing is issued. The response includes the expires_at that was signed into the credential.
Once the date has passed, GET /api/verify/{assertion_id} answers { "valid": false, "reason": "expired" } and the badge page says it has expired. The credential file and the badge image can still be downloaded: they are the signed record, and carry the end date themselves. An expiry cannot be edited after issue, because it is signed into the credential. To renew, issue the badge again once the award has expired, or revoke the award and issue again before then. Repeating a request with the same external_id or Idempotency-Key returns the original award with its original expiry, so a different expires_at on the repeat is ignored. Incredify does not renew awards automatically or send expiry reminders. GET /api/v1/awards status=active means not revoked: compare expires_at with the current time to find awards that have lapsed.
Retrying safely
Networks time out, and automation tools retry. Two things make a retry safe, and you can use either or both:
- `external_id` (in the body) — your own identifier for the award, such as an enrollment or CRM record id. It is unique within your organization and is returned with the award.
- `Idempotency-Key` (a request header) — any unique token for this request, such as a UUID.
Both are 1–200 printable characters without spaces. If you send a request again with the same value, for the same badge and recipient, nothing new is issued: you get 200 with the original award and "replayed": true. If the value was already used for a different badge or recipient, you get 409 idempotency_conflict. A repeat returns the original award as it was issued: a different notify, name, or evidence on the repeat is ignored, and no second email is sent.
Keep personal data out of external_id
external_id is stored as plain text and appears in your organization's data export. Use an opaque record id rather than a student number, name, or email address.
POST /api/v1/issue — safe to repeat
curl -X POST https://incredify.net/api/v1/issue \
-H "Authorization: Bearer ik_your_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7c1f4a0e-2f6b-4b7e-9c55-0d3a1e8b6f21" \
-d '{
"badge_id": "<badge uuid>",
"external_id": "enrollment-48213",
"recipient": { "email": "earner@example.edu" }
}'
# first time -> 201 { "assertion_id": "...", "external_id": "enrollment-48213", ... }
# sent again -> 200 { "assertion_id": "<same>", ..., "replayed": true }Look up and list awards
Read awards back for reconciliation against your registrar, CRM, or student information system. Both endpoints return only your organization's awards.
Responses contain personal data
Every award includes the recipient's email address and name. Keep your API key secret, store it only on your servers, and revoke it under Settings → API access if it may have been exposed.
GET /api/v1/awards/{assertion_id}
curl https://incredify.net/api/v1/awards/3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b \
-H "Authorization: Bearer ik_your_key"
# 200 ->
# {
# "assertion_id": "3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b",
# "badge_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
# "external_id": "enrollment-48213",
# "issued_at": "2026-11-11T10:00:00+00:00",
# "expires_at": null,
# "revoked": false,
# "revoked_at": null,
# "revocation_reason": null,
# "recipient": { "email": "earner@example.edu", "name": "Jane Earner" },
# "claim_url": "https://incredify.net/b/3f2b8c1e-...",
# "verify_url": "https://incredify.net/api/verify/3f2b8c1e-..."
# }An id that doesn't exist, or belongs to another organization, returns 404 award_not_found. external_id, expires_at, revoked_at, and revocation_reason are null when not set. recipient.email is null in the rare case it can't be read.
GET /api/v1/awards
curl "https://incredify.net/api/v1/awards?status=active&limit=50" \
-H "Authorization: Bearer ik_your_key"
# 200 -> { "awards": [ { ...same fields as above... } ], "next_cursor": "eyJ0Ijoi..." }All query parameters are optional and combine with AND. Unknown parameters are ignored. There is no recipient_email parameter: addresses in URLs end up in logs, so a request carrying one returns 400 invalid_request. To find a person's awards, use the search endpoint below.
| Parameter | Meaning |
|---|---|
badge_id | Only awards of this badge (a uuid from GET /api/v1/badges). 404 badge_not_found if it isn't yours. |
external_id | Only the award issued with this external_id. |
issued_after | ISO 8601 date-time such as 2026-09-01T00:00:00Z. Awards issued at or after it. |
issued_before | ISO 8601 date-time. Awards issued before it. |
status | active, revoked, or all (default). |
limit | Awards per page, 1–200 (default 50). |
cursor | The next_cursor from the previous page. |
Pagination. Awards come newest first. When next_cursor is not null, there is another page: send it back unchanged as cursor, with the same filters. A null next_cursor means you have reached the end. Treat the cursor as an opaque string; a cursor we didn't issue returns 400 invalid_request.
POST /api/v1/awards/search
curl -X POST https://incredify.net/api/v1/awards/search \
-H "Authorization: Bearer ik_your_key" \
-H "Content-Type: application/json" \
-d '{ "recipient_email": "earner@example.edu", "status": "active", "limit": 50 }'
# 200 -> { "awards": [ { ...same fields as above... } ], "next_cursor": null }The body takes the same filters as the list (badge_id, external_id, issued_after, issued_before, status, limit, cursor) plus recipient_email (case-insensitive), and the response has the same shape. Send the next_cursor back as cursor in the body, with the same filters. Malformed JSON or an invalid field returns 400 invalid_request.
Revoke and restore awards
Revoke an award when it should no longer count, for example when it was issued in error, and restore it if that changes. The reason you send is kept for your organization's records: it is returned by this API and included in the recipients export, and is not shown on the badge page or returned by the public verification check. Restoring an award clears its reason. Verification reports the award as revoked immediately, and the badge page shows its Revoked banner.
POST /api/v1/awards/{assertion_id}/revoke
curl -X POST https://incredify.net/api/v1/awards/3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b/revoke \
-H "Authorization: Bearer ik_your_key" \
-H "Content-Type: application/json" \
-d '{"reason":"Issued in error"}'
# 200 -> { "assertion_id": "3f2b8c1e-...", "revoked": true, "revoked_at": "...", "revocation_reason": "Issued in error", ... }POST /api/v1/awards/{assertion_id}/restore
curl -X POST https://incredify.net/api/v1/awards/3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b/restore \
-H "Authorization: Bearer ik_your_key"
# 200 -> { "assertion_id": "3f2b8c1e-...", "revoked": false, "revoked_at": null, "revocation_reason": null, ... }Both return the full award object. reason is optional, up to 500 characters. It is returned only to your organization, by this API and in the recipients export. The public verification endpoint (/api/verify/{assertion_id}), which needs no key, reports that the award is revoked and when, and no longer includes a revocationReason field (removed 12 November 2026; until then the reason was returned to anyone with the badge link, so a copy someone saved earlier may still exist); the badge page shows only the revocation date. Restoring an award clears its reason, so keep your own record if you need one. Repeating a revoke or a restore returns 200 with the award unchanged (the first reason and date are kept). An id that does not exist or belongs to another organization returns 404 award_not_found. Restoring when the person has since been issued the same badge again returns 409 duplicate_award.
Errors
Every error is JSON with a stable error code and a readable message. Branch on the code, not the message.
| Status | error | Meaning |
|---|---|---|
| 400 | invalid_request | The body or a header is malformed. details lists the fields. |
| 400 | invalid_expires_at | expires_at is not a valid date, is not later than today (UTC), or is more than 50 years ahead. |
| 401 | invalid_token | Missing, wrong, revoked, or expired key. |
| 403 | plan_required | The organization is not on the Enterprise plan. |
| 403 | account_suspended | The organization is suspended. |
| 403 | insufficient_scope | The key lacks the permission this request needs. required_scope names it. |
| 403 | plan_limit_reached | The yearly issuance limit has been reached. Not returned today, because the API is Enterprise-only and Enterprise has no yearly limit; listed so a client can handle it. |
| 404 | badge_not_found | No such badge in your organization. |
| 404 | award_not_found | No such award in your organization. |
| 409 | duplicate_award | This person already holds an active award of this badge. On issue, the response includes that award's assertion_id, claim_url, and verify_url; on restore it does not. |
| 409 | badge_draft / badge_archived | The badge can't be issued in its current state. |
| 409 | idempotency_conflict | The external_id or Idempotency-Key was already used for a different award. |
| 409 | award_revoked | The award this external_id or Idempotency-Key names has been revoked. To issue again, use a new value. |
| 409 | award_expired | The award this external_id or Idempotency-Key names has passed its valid-until date. To issue again (a renewal), use a new value. |
| 429 | rate_limit_exceeded | Too many requests. See Retry-After. |
| 500 | internal_error | Something failed on our side. Safe to retry if the request carried an Idempotency-Key or an external_id; send the same value again. |
| 503 | service_unavailable | The API is temporarily unavailable. Nothing was done; wait for Retry-After and try again. |
Rate limits
Limits are per key, per minute. Exceeding one returns 429 Too Many Requests with a Retry-After header.
| Plan | Requests per minute |
|---|---|
| Enterprise | 2,000 |
Webhooks
Webhooks send a signed HTTPS request to your own server when awards change, so you do not have to poll. An organization admin sets them up under Settings → Webhooks; they are part of the Enterprise plan. You can add up to 5 endpoints. Each URL must use https:// on the default port (443) and a public hostname, not an IP address, with no username, password or # fragment, and at most 2,048 characters. Reserved and internal names (such as localhost, .local, .internal) and Incredify's own hosts are refused, and so is any name that resolves to a private or reserved address when a request is sent. Your server's certificate must be valid and issued by a publicly trusted authority. Requests do not come from a fixed IP address, so verify the signature rather than allow-listing an address.
| Event | Fires when |
|---|---|
award.issued | A badge is issued to someone. |
award.viewed | The first time a browser loads the public award page. It fires once per award. Anyone with the link can cause it, so it does not prove the recipient opened it and does not identify who did. |
award.revoked | An award is revoked. |
award.restored | A revoked award is restored. |
pathway.completed | Someone completes a pathway. |
Each endpoint chooses which events it receives. The request body is JSON; pathway.completed adds a pathway_id to data; when completing the pathway did not itself award a badge, its award_id is null and the other award fields are absent. external_id is the value you supplied when issuing, or null. The id in the body is the same value as the webhook-id header.
Request body
{
"id": "6b0e2f4a-8c1d-4e57-9a36-2d7f5b1c9e08",
"type": "award.issued",
"created_at": "2026-11-11T10:00:00.000Z",
"data": {
"award_id": "3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b",
"badge_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"external_id": "enrollment-48213",
"issued_at": "2026-11-11T10:00:00+00:00",
"expires_at": null,
"revoked_at": null,
"first_viewed_at": null
}
}No recipient name or email in payloads
Incredify never puts the recipient's name or email address in a payload. Use the award_id to call GET /api/v1/awards/{id} when you need them. Your own external_id is included as you supplied it, so do not put personal data in external_id if you do not want it sent to your endpoint and kept in the delivery record for 30 days.
Verifying the signature
Every request is a POST with content-type: application/json, the user agent Incredify-Webhooks/1, and three headers:
- `webhook-id` — the event id. It is the same on every retry of the same event.
- `webhook-timestamp` — Unix time in seconds when this attempt was signed.
- `webhook-signature` —
v1,followed by the base64 HMAC-SHA256 of{webhook-id}.{webhook-timestamp}.{raw body}. The key is the base64-decoded part of your signing secret after thewhsec_prefix.
The signing secret is shown once, when you add the endpoint or rotate its secret. Rotating replaces it immediately: the old secret stops working at once, with no overlap period. Verify against the raw body exactly as received, and reject any timestamp more than 5 minutes from your clock.
Node.js
const crypto = require("node:crypto");
// rawBody must be the exact bytes received, before any JSON parsing.
function verify(secret, headers, rawBody) {
const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signature = headers["webhook-signature"] || "";
if (!id || !/^\d+$/.test(timestamp || "")) return false;
// Reject anything older (or newer) than 5 minutes.
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const key = Buffer.from(secret.slice("whsec_".length), "base64");
const expected = Buffer.from(
"v1," + crypto.createHmac("sha256", key).update(id + "." + timestamp + "." + rawBody).digest("base64")
);
const got = Buffer.from(signature);
return got.length === expected.length && crypto.timingSafeEqual(got, expected);
}Delivery and retries
- Answer with any
2xxstatus within 5 seconds. The response body is ignored. Redirects are not followed and count as a failure. - Once an event is recorded, delivery is at-least-once: the same event can arrive more than once, so de-duplicate on
webhook-id. In the rare case that Incredify cannot record an event, it is not sent. - Order is not guaranteed. Do not assume events arrive in the order they happened.
- The first attempt is normally made within seconds. When many events happen at once (a large bulk issue, for example) it can be delayed by several minutes; there is no guaranteed upper bound.
- A failed attempt is retried no sooner than 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours after the previous failure. After the seventh failed attempt the delivery is marked failed.
- After 20 failed attempts in a row an endpoint is switched off. Retries and tests count, and any success resets the count. Incredify does not send a notification when this happens: the endpoint shows as off under Settings → Webhooks, where you can switch it back on.
- Events that happen while an endpoint is off, or while the organization is not on an active Enterprise plan, are never sent and are not replayed afterwards. Deliveries already waiting at that moment are marked failed.
- Delivery records are kept for 30 days. Recent deliveries in Settings shows the last 20 for an endpoint.
Send test in Settings sends a ping event with an empty data object to one endpoint and shows the result. A test is not retried, needs the endpoint to be on, and is limited to 5 per minute for the organization.
Exporting everything
GET /api/v1/export returns a full JSON export of your organization. It authenticates with your signed-in admin session, not an API key, and isn't plan-restricted. See Reporting and exports.
Public endpoints
These need no authentication at all — they're what makes a credential independently checkable:
GET /api/verify/<assertion-id>— verify a credential. 60 requests/minute per IP.GET /api/assertions/<assertion-id>/credential.json— the Open Badges 3.0 credential as JSON-LD, with an embedded proof on awards issued from 12 November 2026.GET /api/assertions/<assertion-id>/credential.jwt— the same credential as a signed token (VC-JWT).GET /api/assertions/<assertion-id>/baked.png— the badge image with the credential embedded.GET /issuers/<your-subdomain>/did.json— your published issuer identity and public keys.
Related
Still stuck?
Email us at hello@incredify.net — a human will answer.