RiseTech UnifyID API Documentation

Build secure identity verification into your applications with RiseTech Digital UnifyID's

Get Started

Introduction

Integrate secure, decentralized identity verification into your applications with the RiseTech UnifyID API. Our enterprise-grade platform is built with W3C Decentralized Identifiers (DIDs), allowing you to create seamless, secure and trustworthy user experiences.

What can you do with this API?

Request User Verification

Initiate requests for users to present their digital verified credentials for seamless authentication, choosing between standard or face-check levels of security.

Validate Credentials

Securely receive and validate the authenticity of presented credentials in real-time, whether through a simple SAML assertion or a direct API response.

Issue Custom Credentials

Design and issue your own branded, verifiable credentials to users, with full control over the claims, branding, and optional KYC verification.

Getting Started

Your Quick Path to Integration:
  1. Get Your API Key: Contact your RiseTech account manager to obtain your API key and base URL.
  2. Integration Flows: Review the Integration Flows to choose the pattern that best fits your app.
  3. API Reference: Explore the API Reference for detailed endpoint information.

Integration Flows

1. Credential Issuance Flow

Important Notes:
  • A customer must be created first before you can issue credentials to users
  • The KYC verification step is optional and can be skipped based on your requirements
  • All other steps are mandatory for credential issuance

2. Presentation Flow (Direct API Verification)

Use API Key
Include your API key in the X-API-Key header
Verification Request
Generate URL or QR code for user to verify
Verification Done
Server sends processed results
Success
User authenticated and granted access

Authentication

All API calls require authentication using an API key. Include your API key in the X-API-Key header with every request.

Getting Your API Key

How to get your API Key:
Your API key and base URL will be provided to you during onboarding. Contact your RiseTech account manager or reach out to our support team if you haven't received your credentials.

Making Authenticated Requests

GET
/api/cardtypes/getactivecards

Example: Get active card types with API key authentication

curl -X GET {BASE_URL}/api/cardtypes/getactivecards \
  -H "X-API-Key: your_api_key_here"
Required Header for All API Calls:
X-API-Key: your_api_key_here
Security Best Practices:
  • Never expose your API key in client-side code or public repositories
  • Use environment variables to store your API keys
  • Rotate your API keys periodically
  • Use sandbox API keys for development and testing
Usage & Billing:
Monitor your API usage, view rate limits, and manage billing through your RiseTech dashboard.

SAML 2.0 Integration

Configure your application as a Service Provider (SP) to use UnifyID as a SAML Identity Provider (IdP).

Why Choose SAML? Your application only needs to "speak SAML" - we handle the entire UnifyID verification process internally.

SAML Endpoints

GET
/api/saml/idp/metadata

Get IdP metadata XML

GET POST
/api/saml/idp/sso

SAML SSO endpoint - accepts AuthnRequest via redirect or POST binding

Authentication Context Classes

Level Context URI Use Case
Standard https://risetech.id/saml/contexts/unifyid-standard Regular authentication via mobile app
Face Check https://risetech.id/saml/contexts/unifyid-facecheck High-security with biometric face check

Direct API Integration

For applications that cannot use SAML or require a custom user interface.

POST
/api/verification/verification-request

Initiate a verification request and receive a QR code

curl -X POST {BASE_URL}/api/verification/verification-request \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "UserGUID": "BD275F05-A037-4B3E-93DC-008E5B13F3C8",
    "CustomerGUID": "BF5F8407-DBEB-45DC-8E51-B0B784D8042C",
    "faceCheck": false,
    "isMobile": false,
    "purpose": "Log in to the portal.",
    "cardTypeGuid": "3E524D30-F5F2-47F4-980E-96EE3A0A9201"
  }'
GET
/api/callback/request-status?id={requestId}

Poll for verification status (every 3 seconds)

GET
/api/status/request-status-stream?id={requestId}

Monitor status using Server-Sent Events (SSE) - Alternative to polling

Customer Management

POST
/api/customers/createcustomer

Create a new customer organization

curl -X POST {BASE_URL}/api/customers/createcustomer \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Acme Corporation",
    "email": "admin@acme.com",
    "firstName": "John",
    "lastName": "Doe"
  }'
GET
/api/customers/getcustomer?customerGuid={guid}

Retrieve customer details by GUID

PUT
/api/customers/updatecustomer?customerGuid={guid}

Update existing customer information

User Management

POST
/api/users/createuser

Create a new user under a customer account

curl -X POST {BASE_URL}/api/users/createuser \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customerGuid": "BF5F8407-DBEB-45DC-8E51-B0B784D8042C",
    "email": "john.smith@acme.com",
    "firstName": "John",
    "lastName": "Smith"
  }'
GET
/api/users/getuser?userGuid={guid}

Retrieve user details by GUID

PUT
/api/users/updateuser?userGuid={guid}

Update existing user information

Credentials & Cards

GET
/api/cardtypes/getactivecards

Get all active card types available for issuance

POST
/api/customcredentials/createcustomcredential?customerGuid={guid}

Create a custom credential type with branding and claims

GET
/api/credentials/getusercredentials?userGuid={guid}

Get all credentials issued to a specific user

POST
/api/credentials/revokecredential

Revoke an issued credential

KYC & Issuance Flow

GET
/api/credentials/getidscanqrcode

Generate QR code for ID document scanning

POST
/api/credentials/issuance-request

Issue a verifiable credential to a user

curl -X POST {BASE_URL}/api/credentials/issuance-request \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "UserGUID": "BD275F05-A037-4B3E-93DC-008E5B13F3C8",
    "CustomerGUID": "BF5F8407-DBEB-45DC-8E51-B0B784D8042C",
    "Claims": {
      "given_name": "John",
      "family_name": "Smith",
      "mail": "john.smith@example.com"
    },
    "IsMobile": false,
    "cardTypeGuid": "3E524D30-F5F2-47F4-980E-96EE3A0A9201",
    "purpose": "Employee credential issuance"
  }'
POST
/api/credentials/sendemail

Send verification code via email

Error Codes

The API uses standard HTTP response codes and returns detailed error information in JSON format.

HTTP Status Codes

Code Status Description
200 OK Request succeeded
201 Created Resource created successfully
400 Bad Request Invalid request parameters or body
401 Unauthorized Missing or invalid API key
403 Forbidden API key doesn't have permission
404 Not Found Resource not found
429 Too Many Requests Usage limit exceeded
500 Internal Server Error Server error - contact support

Error Response Format

{
  "error": "API key is required",
  "errorCode": "missing_api_key",
  "correlationId": "be0adcce-deca-4017-a132-71f99250c87e"
}

Error Codes Reference

HTTP Code Error Code Description Resolution
401 missing_api_key No API key provided Add X-API-Key header
401 invalid_api_key API key not found or inactive Check key in Dashboard
429 usage_limit_exceeded Plan limit reached Upgrade or wait for next cycle
500 validation_service_error Unable to validate API key Retry; contact support
500 internal_error Unexpected server error Include correlationId in support
Tip: Always include the correlationId from error responses when contacting support.

Best Practices

DO
  • Use environment variables for API keys
  • Implement comprehensive error handling
  • Use HTTPS for all endpoints
  • Rotate API keys periodically
  • Set reasonable timeouts
  • Monitor usage via Dashboard
DON'T
  • Store API keys in source code
  • Log sensitive data or API keys
  • Share API keys via email/chat
  • Use production keys in testing
  • Skip error handling
  • Expose internal error messages

SDKs & Libraries

Coming Soon

Native SDKs to make integration even easier

JavaScript/TypeScript

In Development

Python

In Development

.NET/C#

In Development

RiseTech Wallet

Coming Soon

A comprehensive digital wallet for managing your digital identity

Digital ID Cards

Securely store and manage all your digital identity cards

NFC Support

Tap to share your credentials

Secure & Private

End-to-end encryption with biometric authentication

Support

Email Support

Get in Touch

Response within 24 hours

Telegram

Join our channel

Real-time support

Microsoft Teams

Join our team

Collaborative support