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

# Introduction

> Integrate with YoID to issue and verify credentials across the YOMA ecosystem.

## What You Can Do

The YoID REST API lets your organisation participate in the YOMA ecosystem as a **credential issuer**, a **credential verifier**, or both.

<CardGroup cols={2}>
  <Card title="Learning & Impact Partners" icon="graduation-cap" href="/api/issuers/overview">
    Issue verifiable credentials to youth when they complete programmes, achieve milestones, or participate in impact activities
  </Card>

  <Card title="Employers & Opportunity Providers" icon="briefcase" href="/api/verifiers/overview">
    Request and verify youth credentials instantly — no manual document checks, no three-week turnarounds
  </Card>
</CardGroup>

## Two Authentication Contexts

The YoID platform has two distinct authentication realms. Understanding this upfront prevents confusion during integration.

| Realm                           | Who                  | Purpose                                                                                         |
| ------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------- |
| **Product Hub** (`product-hub`) | Your organisation    | Authenticate your API calls to issue or verify credentials                                      |
| **Consumers** (`consumers`)     | Youth wallet holders | Authenticate youth into their wallet to accept credentials and respond to verification requests |

As an integrating partner, you authenticate via the **Product Hub** realm. The youth-side authentication is handled by the wallet — you don't need to manage it directly, but understanding that it exists helps when debugging the boundary between "I issued a credential" and "the youth received it."

<Note>
  Your API calls operate in the Product Hub realm. The youth's wallet operates in the Consumers realm. These are separate — a credential you issue travels across this boundary asynchronously.
</Note>

## APIs

The YoID platform exposes three core services:

| API                         | Base URL                                            | What It Does                                                                                          |
| --------------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Consumer Onboarding API** | `https://test.didxtech.com/consumer-onboarding/api` | Provisions a youth account — creates a Keycloak identity and initialises a wallet tenant              |
| **Me Creds API**            | `https://test.didxtech.com/me-creds/api`            | Credential templates, issuance, presentation templates, verification requests                         |
| **Me Wallet API**           | `https://test.didxtech.com/me-wallet/api`           | Full wallet engine — credential delivery, acceptance/rejection, presentation approvals, user profiles |

### Environments

| Environment    | Base URL                    | Purpose                                   |
| -------------- | --------------------------- | ----------------------------------------- |
| **Test**       | `https://test.didxtech.com` | Build and validate your integration       |
| **Production** | Provided during go-live     | Live credential issuance and verification |

<Warning>
  All examples in this documentation use the **test environment**. Your `clientId` and `clientSecret` are environment-specific — test credentials do not work in production. Contact the YoID team to initiate production onboarding once your integration is validated in the test environment.
</Warning>

## What You'll Need

Before you start coding, make sure you have:

1. A `clientId` and `clientSecret` from the YoID team (see [Prerequisites](/api/prerequisites))
2. An HTTPS callback URL if you plan to receive webhook notifications
3. A test youth account to validate your credential flow end-to-end

## Quick Look

Here's what issuing a credential looks like — four API calls from template to delivery:

```bash theme={null}
# 1. Authenticate
curl -X POST "https://test.didxtech.com/iam/realms/product-hub/protocol/openid-connect/token" \
  -d "grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret"

# 2. Create a credential template (once)
curl -X POST "https://test.didxtech.com/me-creds/api/templates/credentials" \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "Web Dev Completion", "code": "course-completion", ...}'

# 3. Issue a credential to a youth
curl -X POST "https://test.didxtech.com/me-creds/api/credentials/issuance" \
  -H "Authorization: Bearer <token>" \
  -d '{"credentialTemplateId": "<template_id>", "attributes": {...}}'

# 4. Deliver to youth's wallet
curl -X POST "https://test.didxtech.com/me-wallet/api/orgs/credentials" \
  -H "Authorization: Bearer <token>" \
  -d '{"credentialOffer": "<offer_uri>", "recipient": "[email protected]"}'
```

## Getting Started

<Steps>
  <Step title="Read the Prerequisites">
    Understand partner onboarding and what credentials you'll receive — [Prerequisites](/api/prerequisites)
  </Step>

  <Step title="Set Up Authentication">
    Learn how to obtain and manage access tokens — [Authentication](/api/authentication)
  </Step>

  <Step title="Choose Your Workflow">
    Follow the [Issuer workflow](/api/issuers/overview) to issue credentials, or the [Verifier workflow](/api/verifiers/overview) to verify them
  </Step>
</Steps>