Roles and actions

How a person gets an access token, the roles they can hold, and the credential loop every credential is issued through

Every credential is issued through the same loop, and anyone who takes part in that loop needs an access token first.

This page covers the access token, the roles people play, the credential loop, and the six actions people take inside it.

Start with an access token

Every person who takes part needs an access token: an alias held in their own wallet. You create it for them in one call. Andamio builds, sponsors and submits the transaction, so nobody signs.

Give someone an access token
Andamio
POST /accounts/create
One call. Andamio builds, sponsors and submitsPoll GET /addresses/{address}/accounts

Aliases are public and permanent. GET /accounts/{alias}/availability tells you first whether an alias is free.

Roles

A person with an access token takes part in a course in one of three ways. Two are roles. The third is open to anyone.

Course owner
Creates the course and names its teachers.
Whoever creates the course.
Teacher
Defines credentials and accepts evidence.
Named by the course owner.
Learner
Submits evidence and claims the credential.
Not granted. Anyone with an access token who submits evidence.

The credential loop

Once a person holds an access token, every action they take runs the same four steps.

01
Build
POST the action. Andamio returns an unsigned transaction.
02
Sign
The person taking the action signs it in their wallet.
03
Submit
POST /submit. Andamio adds its sponsorship and submits it.
04
Poll
Read the action's route until the result shows.

Andamio sponsors every transaction, so nobody holds ADA or pays a fee. People sign with a social login or a browser wallet.

For developers, API integration has the request for each action and every error. The Issuer API reference has the full schemas.

Build returns an unsigned_tx, plus a course_id or credential_hashes when the action creates one.
Sign is a partial signature from the wallet that holds the acting alias, the alias field in the request (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.
Submit takes the signed transaction hex as tx and returns the tx_hash.
Poll reads the route on each action card below. 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.

The six actions

Each card shows the action, the role that signs it, and that action's run through the loop.

Set up

1
Create a course
Course owner
POST /courses/create
BuildSign · Course ownerSubmitPoll GET /courses/{course_id}
2
Name the teachers
Course owner
POST /courses/{course_id}/teachers
BuildSign · Course ownerSubmitPoll GET /courses/{course_id}/teachers
3
Define a credential
Teacher
POST /courses/{course_id}/credentials/create
BuildSign · TeacherSubmitPoll GET /courses/{course_id}

Earn

4
Submit evidence
Update it until it is accepted.
Learner
POST /courses/{course_id}/credentials/{credential_hash}/evidence/submit…/evidence/update
BuildSign · LearnerSubmitPoll GET /accounts/{alias}/submissions
5
Accept evidence
In batches, all or nothing.
Teacher
POST /courses/{course_id}/credentials/evidence/approve
BuildSign · TeacherSubmitPoll GET /courses/{course_id}/credentials/issuances
6
Claim the credential
Learner
POST /courses/{course_id}/credentials/claim
BuildSign · LearnerSubmitPoll GET /accounts/{alias}/credentials

A few details change how you build on these:

Create a course can name the first teachers. POST /courses/create takes a teachers list, which defaults to the course owner. Use the teachers route to change the list later.
Accept is accept-only and all or nothing. If any learner in the batch was already assessed or has no submission, the whole batch fails and the error names every such learner. Each learner accepted uses one Credentials unit.
Claiming ends enrollment. A learner who claims a credential is unenrolled from the course.
A teacher can remove a credential definition. POST /courses/{course_id}/credentials/remove takes the hashes to remove, and a teacher signs it. It removes a definition from the course. It does not edit one.

The three identifiers

Identifier	What it is	Where it comes from
`course_id`	The on-chain course	Returned by `POST /courses/create`
`credential_hash`	The hash of the credential's statements, in order	Returned by `POST /courses/{course_id}/credentials/create` as `credential_hashes`, in the same order as `credentials_to_add`
Evidence	The learner's reference to their work	Sent as `evidence_info` on submit and update, read back as `evidence_hash`

A credential is identified by the pair course_id and credential_hash. A hash alone does not name it.

Evidence is free text of up to 140 characters. A hash of the evidence is recommended, and a public URL is fine where the evidence is already public. It is written to the chain as sent, so it is public and permanent. Never put personal data in it.