API integration

This page is for developers who integrate Andamio Issuer into your systems. It follows Roles and actions: read that first for the access token, the roles and the credential loop. Here, each action gets its request, who signs it and what to read when it is done.

Work through it on preprod before you go live on mainnet. The Issuer API reference has every route with its full request and response schema.

Connect

Andamio Issuer is one REST API under one namespace, /issuer/v1.

Your key decides the network. Send your Andamio Issuer API key in the X-API-Key header on every request. It is the only key the routes take, with no end-user token. A developer key gets 403.

Check the key before anything else with GET /config:

curl https://preprod.api.andamio.io/issuer/v1/config \
  -H "X-API-Key: $ANDAMIO_API_KEY"

A working key returns 200:

{
  "project_id": "<project id>",
  "network_id": "preprod"
}

network_id is preprod or mainnet, and it should match the network you expect. project_id is the value social login needs. A 401 means the key is missing or invalid.

GET /quota shows what is left in your plan.

For preprod, set up three CIP-30 browser wallets, one each for a course owner, a teacher and a learner. They need no ADA. The examples below use the aliases acme-owner, acme-teacher and acme-learner.

Give each person an access token

Call this once for each person, with their wallet's address as receiver_address.

POST /accounts/create
{ "alias": "acme-owner", "receiver_address": "addr_test1..." }

Andamio builds, sponsors and submits this one itself, and returns a tx_hash. Nobody signs. Poll GET /addresses/{address}/accounts until the alias appears. GET /accounts/{alias}/availability tells you first whether an alias is free.

Run the six actions

Each of these returns an unsigned_tx and runs the credential loop:

1. The wallet that holds the acting alias, the alias in the request body, signs it as a partial signature (CIP-30 signTx with partialSign set to true). Raw CIP-30 returns only the witness set, so add it to the transaction before you submit. Most wallet libraries do this for you.
2. Send the signed transaction hex to POST /submit as tx. Andamio adds its sponsorship, submits it and returns the tx_hash.
3. Poll the read each action names until the result shows. There is no transaction-status route. GET /accounts/{alias}/activity shows every event for an account with its transaction hash, so it works as a poll for any action.

1. Create a course

The course owner signs.

POST /courses/create
{ "alias": "acme-owner", "teachers": ["acme-teacher"] }

The response carries the new course_id. Poll GET /courses/{course_id} until the course returns. The teachers list defaults to the course owner.

2. Name the teachers

The course owner signs. Use this to add or remove teachers after the course exists.

POST /courses/{course_id}/teachers
{ "alias": "acme-owner", "teachers_to_add": ["acme-teacher-2"], "teachers_to_remove": [] }

Poll GET /courses/{course_id}/teachers until the list shows the change.

3. Define a credential

A teacher signs.

POST /courses/{course_id}/credentials/create
{
  "alias": "acme-teacher",
  "credentials_to_add": [
    {
      "slts": ["Completed security awareness training"],
      "allowed_student_state_ids": [],
      "prereq_credential_hashes": []
    }
  ]
}

The response carries credential_hashes, one for each definition, in the same order as credentials_to_add. Poll GET /courses/{course_id} until the credential is listed with a defined_tx. How it works has the rules for a statement.

To take a definition out of a course, a teacher signs POST /courses/{course_id}/credentials/remove with the hashes to remove. Nothing can be edited.

4. Submit evidence

The learner signs.

POST /courses/{course_id}/credentials/{credential_hash}/evidence/submit
{ "alias": "acme-learner", "evidence_info": "<hash of the learner's evidence>" }

evidence_info is up to 140 characters, written to the chain as sent. Send a hash of the evidence, or a public URL if the evidence is already public, and never personal data. Poll GET /accounts/acme-learner/submissions until the submission shows with status pending. Until it is accepted, the learner can replace it with .../evidence/update.

5. Accept evidence

A teacher signs. Accept takes a batch of learners.

POST /courses/{course_id}/credentials/evidence/approve
{ "alias": "acme-teacher", "approvals": ["acme-learner"] }

Poll GET /courses/{course_id}/credentials/issuances until the learner shows an approved_tx. Each learner accepted uses one Credentials unit from your plan.

The batch is all or nothing. If any learner in it was already assessed or has no submission, the whole batch fails and the error names every such learner.

6. Claim the credential

The learner signs.

POST /courses/{course_id}/credentials/claim
{ "alias": "acme-learner" }

Poll GET /accounts/acme-learner/credentials until the credential is listed with a claimed_tx. The learner now holds the credential, and claiming unenrolls them from the course.

Go live with social login

In production, most people sign with a social login instead of a browser wallet. Social login uses the project_id from GET /config, and it works only on a sign-in domain Andamio has allowlisted. Register your domain early, as Before you start describes.

Reads

Reads cover courses, credentials, teachers, learners, and per-account views of credentials, submissions, reviews and activity. Results are always limited to the courses your key holds.

Snapshot lists page with page and limit. Activity feeds page with an opaque cursor. limit defaults to 25, with a maximum of 100.

Errors

Errors return an error object with a code and a message. The code is stable, so match on it rather than on the message.

An error on a limit can name internal fields, such as modules_to_add, instead of the reference's credentials_to_add.

How it relates to the Andamio API

Issuer and the Andamio API are separate products with separate keys, both built on the Andamio Protocol. Issuer covers issuing credentials and sponsors every transaction. The Andamio API gives developers the whole protocol, and they decide who funds each transaction. If you are building something beyond credential issuance, use the Andamio API.

Questions about an integration go to Support.