Institution Automation

Auth model

API-key machine writes

Institution systems use tenant API keys with explicit scopes for issue and revoke operations.

Write behavior

Queued write ingress

Programmatic issue and revoke requests are queued, then converted into signed credential records when processed.

Operational state

Lifecycle is explicit

Assertions track the lifecycle behind each signed credential: active, suspended, revoked, or expired.

When to use this surface

Best fit

Your institution evaluates eligibility outside CredTrail

Use this model when a SIS, LMS, registrar workflow, or departmental script determines that a learner completed the requirement and then calls CredTrail to issue or revoke the badge. CredTrail stores the assertion as the operational record and publishes the signed OB3 credential and public badge URL from that record.

Not this surface

Standards-based learner or wallet access

If you need subject-scoped OB3 access, learner wallet delivery, or public verification payloads, use the dedicated guides instead of the tenant automation routes below.

Setup and operational endpoints

GETTenant admin

/v1/tenants/:tenantId/api-keys

Lists active and revoked API keys for the tenant.

POSTTenant admin

/v1/tenants/:tenantId/api-keys

Creates a new tenant API key. Plaintext key material is returned only once on creation.

POSTTenant admin

/v1/tenants/:tenantId/api-keys/:apiKeyId/revoke

Revokes a tenant API key so it can no longer issue or revoke credentials.

POSTAPI key

/v1/programmatic/issue

Queues a badge issuance request using the tenant API key scope queue.issue.

POSTAPI key

/v1/programmatic/revoke

Queues a badge revocation request using the tenant API key scope queue.revoke.

GETIssuer session

/v1/tenants/:tenantId/assertions/:assertionId/lifecycle

Returns current lifecycle state plus the recorded lifecycle event history.

POSTIssuer session

/v1/tenants/:tenantId/assertions/:assertionId/lifecycle/transition

Applies a manual lifecycle transition such as suspension, revocation, or reinstatement.

POSTIssuer session

/v1/tenants/:tenantId/assertions/manual-issue

Issues a badge through an authenticated issuer/admin session instead of an API key.

Assertion and signing model

Credential records

Assertions are the operational lifecycle record; credentials are the signed public artifact.

• Programmatic and manual issue flows create a tenant-scoped assertion record.
• The issued artifact is an Open Badges 3.0 JSON-LD Verifiable Credential.
• CredTrail signs issued credentials and status-list credentials with DataIntegrityProof using eddsa-rdfc-2022.
• Public badge URLs use friendly identifiers; legacy /credentials/v1/:credentialId routes still resolve tenant-scoped assertion IDs.
• Assertion lifecycle transitions update the live verification result without rewriting the immutable issued credential.

Write contract

Operational contract

Programmatic writes are idempotent, attributed, and intentionally narrow.

• Send x-api-key on programmatic write requests.
• idempotencyKey is required on all programmatic writes.
• Actor attribution is derived from the API key owner, not a caller-supplied user ID.
• Internal /v1/issue and /v1/revoke routes are not public integration APIs.
• Successful write requests return 202 Accepted with queue metadata.

Required issue fields

tenantId, badgeTemplateId, recipientIdentity, recipientIdentityType, and idempotencyKey

Optional issue fields

recipientIdentifiers with types like studentId, emailAddress, sourcedId, or did

Required revoke fields

tenantId, assertionId, reason, and idempotencyKey

Lifecycle states

active, suspended, revoked, and expired

Standard automation flow

1. Create and store a tenant API key. A tenant admin creates the key once, records the plaintext secret securely, and grants only the scopes needed by the integration.

2. Queue issuance when your source system confirms eligibility. Your SIS, LMS, registrar script, or departmental workflow calls the programmatic issue route. The worker later signs the OB3 credential and stores the assertion-backed artifact.

3. Monitor assertion state and apply lifecycle changes when needed. Use lifecycle reads for operational visibility and transitions for holds, revocations, or reinstatement.

Request examples

Queue issue

curl -sS https://credtrail.org/v1/programmatic/issue \
  -H "content-type: application/json" \
  -H "x-api-key: $CREDTRAIL_API_KEY" \
  -d '{
    "tenantId": "tenant_example",
    "badgeTemplateId": "badge_template_sakai_commits",
    "recipientIdentity": "learner@example.edu",
    "recipientIdentityType": "email",
    "recipientIdentifiers": [
      {
        "identifierType": "studentId",
        "identifier": "12345678"
      }
    ],
    "idempotencyKey": "sis-issue-tenant_example-12345678-20260307"
  }' | jq

{
  "status": "queued",
  "channel": "programmatic_api_key",
  "jobType": "issue_badge",
  "assertionId": "tenant_example:7df18c9c-1d19-42d7-9aa7-bd17e6d3cf74",
  "idempotencyKey": "sis-issue-tenant_example-12345678-20260307"
}

Queue revoke

curl -sS https://credtrail.org/v1/programmatic/revoke \
  -H "content-type: application/json" \
  -H "x-api-key: $CREDTRAIL_API_KEY" \
  -d '{
    "tenantId": "tenant_example",
    "assertionId": "tenant_example:7df18c9c-1d19-42d7-9aa7-bd17e6d3cf74",
    "reason": "Credential revoked by issuer after policy review",
    "idempotencyKey": "sis-revoke-tenant_example-12345678-20260307"
  }' | jq

{
  "status": "queued",
  "channel": "programmatic_api_key",
  "jobType": "revoke_badge",
  "assertionId": "tenant_example:7df18c9c-1d19-42d7-9aa7-bd17e6d3cf74",
  "revocationId": "tenant_example:0f9a0e8b-39db-4b6f-845f-9ec0f4442de2",
  "idempotencyKey": "sis-revoke-tenant_example-12345678-20260307"
}

Read lifecycle

curl -sS https://credtrail.org/v1/tenants/tenant_example/assertions/tenant_example:7df18c9c-1d19-42d7-9aa7-bd17e6d3cf74/lifecycle \
  -H "Authorization: Bearer $ISSUER_SESSION_TOKEN" | jq

{
  "assertionId": "tenant_example:7df18c9c-1d19-42d7-9aa7-bd17e6d3cf74",
  "tenantId": "tenant_example",
  "state": "active",
  "source": "default_active",
  "reasonCode": null,
  "reason": null,
  "transitionedAt": "2026-03-07T18:02:11.000Z",
  "revokedAt": null,
  "events": []
}

Manual transition

curl -sS https://credtrail.org/v1/tenants/tenant_example/assertions/tenant_example:7df18c9c-1d19-42d7-9aa7-bd17e6d3cf74/lifecycle/transition \
  -H "Authorization: Bearer $ISSUER_SESSION_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "toState": "revoked",
    "reasonCode": "issuer_requested",
    "reason": "Credential revoked by issuing office",
    "transitionSource": "manual"
  }' | jq

Related docs

Open Badges 3.0 APIUse the subject-scoped standards surface for OB3 discovery, credential reads, and profile sync.Public verification and downloadsDocument the URLs employers, recipients, and auditors use after the badge has been issued.Wallet import and credential exchangeSee the learner-facing OID4VCI and public badge delivery path.