Connect your systems to Certrust

1. Check your plan

API keys are part of the Pro and Enterprise plans, including while you are on a trial of one. Sign in and open Manage → API keys. If you see "API keys are part of the paid plans", go to Billing to upgrade first.

2. Create a key

1. Go to Manage → API keys.
2. Give the key a name that says where it will be used, such as "Student records system" or "Moodle". You will see this name in the list and in the audit log.
3. Choose the permissions. Give a key only what its system needs:

4. Optionally set an expiry date. Leave it empty for a key that works until you revoke it.
5. Select Create key.

3. Hand the key to your IT team

The key starts with crt_ and is shown only once. Copy it straight away.

• Send it through a password manager or your organisation's secure file sharing. Don't paste it into email or chat.
• Ask your IT team to store it in their system's secret settings, not in code or documents.
• Send them this guide too: Part 2 has everything they need.

If you lose the key, you can't see it again. Revoke it and create a new one.

4. Look after your keys

• Check activity. The API keys page shows when each key was last used. A key nobody uses any more should be revoked.
• Revoke straight away if a key may have been exposed, or a system or supplier is retired. Anything using it stops working immediately.
• Replace keys regularly. Create the new key, have your IT team switch over, then revoke the old one.
• Paused keys. If your plan no longer includes API access, keys show as paused and stop working until you upgrade again.
• Audit trail. Every credential issued or revoked with a key is recorded against that key's name.

Authentication

Send the key as a Bearer token on every request. Check it works, and see its organisation, permissions and the endpoints it may call:

curl https://api.certrust.app/api/api-keys/me \
  -H "Authorization: Bearer $CERTRUST_API_KEY"

The response includes issuerProfileId, which you need in the next step. Keep the key on your server; never put it in a website or mobile app.

Find the achievement ID

Every credential is issued for an achievement (the course, programme or event someone completed). Create the achievement in Certrust first. To find its numeric ID, either:

• open it on the Issue page in Certrust: the number after ?achievement= in the address is the ID, or
• list the achievements the key's owner created:

curl https://api.certrust.app/api/achievements/creator/{issuerProfileId} \
  -H "Authorization: Bearer $CERTRUST_API_KEY"

Issue a credential

The recipient gets an email with a link to their credential. expirationDate and customFields are optional. customFields are only needed if your organisation has set up custom attributes in the Design Studio. Send them by key; required ones must be included, and keys that don't exist are ignored.

curl -X POST https://api.certrust.app/api/credentials/issue \
  -H "Authorization: Bearer $CERTRUST_API_KEY" \
  -H "Idempotency-Key: student-1042-course-7" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "achievementId": 12,
      "recipient": { "name": "Ada Lovelace", "email": "ada@example.edu" },
      "expirationDate": "2028-06-30",
      "customFields": { "training_date": "2026-10-01" }
    }
  }'

The same request in JavaScript (Node.js 18+):

const res = await fetch('https://api.certrust.app/api/credentials/issue', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.CERTRUST_API_KEY}`,
    'Idempotency-Key': `student-${student.id}-course-${course.id}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      achievementId: 12,
      recipient: { name: student.name, email: student.email },
    },
  }),
})
if (!res.ok) throw new Error((await res.json()).error?.message)
const { credential } = await res.json()
console.log(credential.credentialId) // urn:uuid:…

And in Python:

import os, requests

res = requests.post(
    "https://api.certrust.app/api/credentials/issue",
    headers={
        "Authorization": f"Bearer {os.environ['CERTRUST_API_KEY']}",
        "Idempotency-Key": f"student-{student_id}-course-{course_id}",
    },
    json={"data": {
        "achievementId": 12,
        "recipient": {"name": name, "email": email},
    }},
    timeout=30,
)
res.raise_for_status()
print(res.json()["credential"]["credentialId"])

Response. Keep credential.id if you may need to revoke later:

{
  "credential": {
    "id": 201,
    "documentId": "mosfeiitve177d1bpztvbfej",
    "credentialId": "urn:uuid:1713ee84-87c0-4564-84b1-d615b20a5e59",
    "name": "Data Skills Workshop",
    "issuanceDate": "2026-10-03T04:12:09.000Z",
    "revoked": false
  },
  "openBadge": { "…": "the signed Open Badges 3.0 credential" },
  "notification": { "…": "email delivery details" }
}

Issue to a whole group

Send a whole class or cohort in one request. Each recipient gets their own result, so one bad email doesn't stop the rest. With "skipExisting": true, people who already hold this credential are skipped. That makes it safe to send the full list again, for example from a nightly sync.

curl -X POST https://api.certrust.app/api/credentials/batch-issue \
  -H "Authorization: Bearer $CERTRUST_API_KEY" \
  -H "Idempotency-Key: graduation-2026-batch-3" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "achievementId": 12,
      "skipExisting": true,
      "recipients": [
        { "name": "Ada Lovelace", "email": "ada@example.edu" },
        { "name": "Alan Turing", "email": "alan@example.edu" }
      ]
    }
  }'

{
  "results": [
    { "success": true, "recipient": "ada@example.edu", "data": { "…": "the credential" } },
    { "success": true, "skipped": true, "recipient": "alan@example.edu", "note": "Already has this credential" }
  ]
}

A request can carry up to 200 recipients, and we recommend 50: long requests are more likely to be cut off part-way. If one is, resend the same batch with the same Idempotency-Key. For anything larger, use a job.

Very large groups: jobs

For a whole graduating class or a first import, create an issuance job with up to 2,000 recipients. The request returns straight away (status 202) and Certrust works through the list in the background, so nothing depends on one long connection.

curl -X POST https://api.certrust.app/api/issuance-jobs \
  -H "Authorization: Bearer $CERTRUST_API_KEY" \
  -H "Idempotency-Key: graduation-2026" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "achievementId": 12,
      "skipExisting": true,
      "recipients": [
        { "name": "Ada Lovelace", "email": "ada@example.edu" },
        { "name": "Alan Turing", "email": "alan@example.edu" }
      ]
    }
  }'

The response contains the job's documentId. Ask for its progress every few seconds until status is completed, failed or cancelled:

curl https://api.certrust.app/api/issuance-jobs/{documentId} \
  -H "Authorization: Bearer $CERTRUST_API_KEY"

{
  "data": {
    "documentId": "rg69xy94mbvztzpkf84wpwll",
    "status": "running",
    "total": 1200,
    "processed": 340,
    "succeeded": 336,
    "skipped": 3,
    "failed": 1,
    "results": [
      { "recipient": "ada@example.edu", "success": true, "id": 201, "credentialId": "urn:uuid:…" },
      { "recipient": "alan@example.edu", "success": true, "skipped": true, "note": "Already has this credential", "id": 187, "credentialId": "urn:uuid:…" },
      { "recipient": "bad-address", "success": false, "error": "…" }
    ]
  }
}

• Every recipient gets its own result, in the order you sent them, with the credential's id and credentialId.
• A job that is interrupted, for example by a Certrust update, carries on where it stopped and never issues to the same person twice.
• POST /api/issuance-jobs/{documentId}/cancel stops a job. Credentials already issued stay issued.
• An organisation can have 3 jobs in progress at once. Results are kept for 30 days.

Revoke a credential

Needs the Revoke permission. Use the numeric credential.id from the issue response. Verification shows the credential as revoked straight away.

curl -X POST https://api.certrust.app/api/credentials/201/revoke \
  -H "Authorization: Bearer $CERTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Certification lapsed" }'

Safe retries

Networks fail. If a request times out you can't tell whether the credential was issued, and sending it again might issue it twice. Add an Idempotency-Key header to every write request to prevent that:

• Use a value that names the operation, such as student-1042-course-7, up to 255 characters.
• Sending the same key with the same request again returns the first response instead of running it again, with the header Idempotent-Replayed: true. Responses are kept for 24 hours.
• Sending the same key with a different request is refused (422), so one key can't be reused by mistake.
• A retry that arrives while the first request is still running gets 409. Wait a moment and retry.
• Server errors (5xx) are not kept, so retrying after one runs the request again.

Rate limits

Each key can make 120 requests a minute. Every response shows where you stand in the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. Beyond the limit you get 429 with a Retry-After header giving the seconds to wait. A batch or a job counts as one request however many recipients it has, so use those for volume instead of many single requests.

Errors

Errors come back as JSON with a readable message in error.message.

Endpoints by permission

A key can only call the endpoints its permissions allow. Everything else, including billing, account settings and key management, returns 403.

SDK and AI assistants

A JavaScript/TypeScript SDK (with apiKey and idempotencyKey options) and an MCP server for AI assistants such as Claude are in the open-source repository, in the sdk/ and mcp/ folders. For the MCP server, set CERTRUST_API_KEY to your key.

Questions? Contact us from the details at the bottom of this page.