> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dokstamp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Issue Your First Certificate

> A complete end-to-end walkthrough including modules, cohorts, and enrollments.

# Issue Your First Certificate

This guide walks through the full certificate issuance workflow — from institution setup to issuing a verifiable credential with all optional entities included. By the end, you will have a live certificate with a public verification URL.

***

## Before you start

Make sure you have:

* API credentials (email + password)
* Your `X-Tenant` identifier
* A signed PDF of the certificate

Set these environment variables for the examples below:

```bash theme={null}
export API=https://api.dokstamp.com
export TENANT=your-tenant-domain
export TOKEN=""  # Will be set after Step 1
```

***

## Step 1 — Authenticate

```bash theme={null}
TOKEN=$(curl -s -X POST $API/auth/login \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@myschool.edu","password":"secret"}' \
  | jq -r '.access_token')

echo "Token: $TOKEN"
```

***

## Step 2 — Create the Institution

```bash theme={null}
INSTITUTION=$(curl -s -X POST $API/institutions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -d '{
    "name": "Federal University of Technology",
    "country": "Brazil",
    "status": "active"
  }')

INSTITUTION_UUID=$(echo $INSTITUTION | jq -r '.data.uuid')
echo "Institution UUID: $INSTITUTION_UUID"
```

***

## Step 3 — Create a Module

```bash theme={null}
MODULE=$(curl -s -X POST $API/modules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -d "{
    \"name\": \"Software Engineering\",
    \"code\": \"SE301\",
    \"institution_uuid\": \"$INSTITUTION_UUID\",
    \"workload\": 60,
    \"credits\": 3,
    \"modality\": \"hybrid\",
    \"level\": \"undergraduate\"
  }")

MODULE_UUID=$(echo $MODULE | jq -r '.data.uuid')
```

***

## Step 4 — Create the Course

```bash theme={null}
COURSE=$(curl -s -X POST $API/courses \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -d "{
    \"name\": \"Bachelor of Computer Science\",
    \"code\": \"BCS-2024\",
    \"institution_uuid\": \"$INSTITUTION_UUID\",
    \"workload_hours\": 3200,
    \"status\": \"active\"
  }")

COURSE_UUID=$(echo $COURSE | jq -r '.data.uuid')
```

***

## Step 5 — Attach the Module to the Course

```bash theme={null}
curl -X POST "$API/courses/$COURSE_UUID/attach/modules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -d "{
    \"modules\": [
      { \"uuid\": \"$MODULE_UUID\", \"order\": 1, \"is_required\": true }
    ]
  }"
```

***

## Step 6 — Create a Cohort

```bash theme={null}
COHORT=$(curl -s -X POST $API/cohorts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -d "{
    \"course_uuid\": \"$COURSE_UUID\",
    \"code\": \"BCS-2024-1\",
    \"modality\": \"hybrid\",
    \"start_date\": \"2024-02-01T00:00:00Z\",
    \"end_date\": \"2027-12-31T00:00:00Z\"
  }")

COHORT_UUID=$(echo $COHORT | jq -r '.data.uuid')
```

***

## Step 7 — Create the Student

```bash theme={null}
# Check if student already exists
EXISTING=$(curl -s "$API/students?where[user][email]=maria@email.com" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "X-Tenant: $TENANT")

STUDENT_UUID=$(echo $EXISTING | jq -r '.data[0].uuid // empty')

if [ -z "$STUDENT_UUID" ]; then
  STUDENT=$(curl -s -X POST $API/students \
    -H "Authorization: Bearer $TOKEN" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "X-Tenant: $TENANT" \
    -d '{
      "name": "Maria Fernanda Silva",
      "email": "maria@email.com",
      "date_of_birth": "1998-05-20",
      "gender": "female"
    }')
  STUDENT_UUID=$(echo $STUDENT | jq -r '.data.uuid')
fi

echo "Student UUID: $STUDENT_UUID"
```

***

## Step 8 — Create an Enrollment

```bash theme={null}
ENROLLMENT=$(curl -s -X POST $API/enrollments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -d "{
    \"student_uuid\": \"$STUDENT_UUID\",
    \"course_uuid\": \"$COURSE_UUID\",
    \"cohort_uuid\": \"$COHORT_UUID\",
    \"enrolled_at\": \"2024-02-01\",
    \"completion_status\": \"completed\",
    \"grade\": 9.0,
    \"completed_at\": \"2027-12-20\"
  }")

ENROLLMENT_UUID=$(echo $ENROLLMENT | jq -r '.data.uuid')
```

***

## Step 9 — Upload the PDF

```bash theme={null}
FILE=$(curl -s -X POST $API/files \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "X-Tenant: $TENANT" \
  -F "files[]=@/path/to/diploma-maria.pdf")

FILE_UUID=$(echo $FILE | jq -r '.data[0].uuid')
echo "File UUID: $FILE_UUID"
```

***

## Step 10 — Issue the Certificate

```bash theme={null}
CERTIFICATE=$(curl -s -X POST $API/certificates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Tenant: $TENANT" \
  -d "{
    \"institution_uuid\": \"$INSTITUTION_UUID\",
    \"course_uuid\": \"$COURSE_UUID\",
    \"student_uuid\": \"$STUDENT_UUID\",
    \"cohort_uuid\": \"$COHORT_UUID\",
    \"enrollment_uuid\": \"$ENROLLMENT_UUID\",
    \"file_uuid\": \"$FILE_UUID\",
    \"finish\": true
  }")

echo "Certificate:"
echo $CERTIFICATE | jq '.data | {uuid, status, public_verification_url}'
```

**Output:**

```json theme={null}
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "issued",
  "public_verification_url": "https://verificar.dokstamp.eu/a1b2c3d4"
}
```

The `public_verification_url` is ready to share — no authentication needed to access it.

***

## Next steps

* **Batch issuance** — process hundreds of certificates at once → [Bulk Operations](/en/guides/bulk-operations)
* **Digital badges** — emit Open Badges alongside certificates → [Open Badges](/en/guides/openbadges)
* **Student portfolio** — let the student publish their certificate → [Student Portfolio](/en/guides/student-portfolio)