Credentials API¶

Issue and verify W3C Verifiable Credentials for KYC attestations.

Issue Credential¶

Issue a signed KYC credential for a verified identity.

Endpoint¶

POST /api/v1/issue

Authentication¶

Requires Authorization: Bearer <supabase_jwt> header.

Request Body¶

{
  "email": "user@example.com",
  "phone_number": "+15551234567",
  "full_name": "John Doe",
  "dob": "1990-01-15",
  "tier": "Tier1"
}

Field	Type	Required	Description
`email`	string	Yes	User's email address
`phone_number`	string	Yes	Phone number in E.164 format
`full_name`	string	Yes	User's full legal name
`dob`	string	Yes	Date of birth (YYYY-MM-DD)
`tier`	string	No	KYC tier: `Tier1`, `Tier2`, `Tier3` (default: Tier1)

Response¶

{
  "status": "issued",
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "public_key": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA...\n-----END PUBLIC KEY-----"
}

Field	Type	Description
`status`	string	`issued` on success
`token`	string	Signed JWT containing the Verifiable Credential
`public_key`	string	PEM-encoded public key for verification

Verify Credential¶

Verify a previously issued KYC credential.

Endpoint¶

POST /api/v1/verify

Authentication¶

Requires X-API-Key header with your API key.

Request Body¶

{
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "public_key_pem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA...\n-----END PUBLIC KEY-----"
}

Field	Type	Required	Description
`token`	string	Yes	The JWT credential to verify
`public_key_pem`	string	Yes	PEM-encoded public key from issuance

Response¶

Valid Credential¶

{
  "valid": true,
  "payload": {
    "sub": "user_123",
    "iss": "did:kyc:issuer-firm-b",
    "vc": {
      "@context": ["https://www.w3.org/2018/credentials/v1"],
      "type": ["VerifiableCredential", "KYCCredential"],
      "credentialSubject": {
        "id": "did:kyc:user:abc123",
        "full_name": "John Doe",
        "tier": "Tier1"
      }
    }
  }
}

Invalid Credential¶

{
  "valid": false,
  "error": "Signature verification failed"
}

Credential Structure¶

The issued credential follows the W3C Verifiable Credentials standard:

{
  "sub": "user_id",
  "iss": "did:kyc:issuer-firm-b",
  "nbf": 1705312200,
  "jti": "unique-credential-id",
  "vc": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1"
    ],
    "type": [
      "VerifiableCredential",
      "KYCCredential"
    ],
    "issuanceDate": "2024-01-15T10:30:00Z",
    "credentialSubject": {
      "id": "did:kyc:user:phone_hash",
      "full_name": "John Doe",
      "tier": "Tier1",
      "phone_number": "+15551234567"
    }
  }
}

Example¶

Issue (cURL)Verify (cURL)

curl -X POST https://api.circuitkyc.com/api/v1/issue \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_supabase_jwt" \
  -d '{
    "email": "john.doe@example.com",
    "phone_number": "+15551234567",
    "full_name": "John Doe",
    "dob": "1990-01-15",
    "tier": "Tier1"
  }'

curl -X POST https://api.circuitkyc.com/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_your_api_key" \
  -d '{
    "token": "eyJhbGciOiJFZERTQSIs...",
    "public_key_pem": "-----BEGIN PUBLIC KEY-----\n..."
  }'

Credit Cost¶

Issue: 10 credits
Verify: 1 credit

Security Considerations¶

Store credentials securely - JWT tokens should be stored encrypted
Validate expiration - Check nbf (not before) claim
Verify issuer - Ensure iss matches expected issuer DID
Check revocation - Credentials can be revoked; always verify before accepting