Identity API

The Identity API manages decentralized identities. Users authenticate with DID-based challenges, store verifiable credentials, share claims selectively, and maintain linked accounts.

Base URL: https://identity.solidus.network/v1

Authentication

Request Challenge

Begin a DID authentication flow by requesting a challenge for a specific DID. The challenge must be signed and returned as a Verifiable Presentation.

POST /auth/challenge

Auth: None


// Request body
{
  "did": "did:solidus:testnet:7Hk3mRtQZvXp2nBw9Lj4K"
}


// Response 200
{
  "challengeId": "chl_3Vn9wLkDfT",
  "challenge": {
    "nonce": "a1b2c3d4e5f6789012345678",
    "domain": "identity.solidus.network",
    "expiresAt": "2026-05-07T14:35:00Z"
  }
}

Verify Challenge

Submit a signed Verifiable Presentation to complete authentication and receive a JWT.

POST /auth/verify

Auth: None


// Request body
{
  "challengeId": "chl_3Vn9wLkDfT",
  "presentation": {
    "@context": ["https://www.w3.org/2018/credentials/v1"],
    "type": ["VerifiablePresentation"],
    "holder": "did:solidus:testnet:7Hk3mRtQZvXp2nBw9Lj4K",
    "proof": {
      "type": "Ed25519Signature2020",
      "created": "2026-05-07T14:30:00Z",
      "challenge": "a1b2c3d4e5f6789012345678",
      "domain": "identity.solidus.network",
      "verificationMethod": "did:solidus:testnet:7Hk3mRtQZvXp2nBw9Lj4K#key-1",
      "proofValue": "z3FXQjecWufY46...yUPgbT"
    }
  }
}


// Response 200
{
  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "usr_7Hk3mRtQZv",
    "did": "did:solidus:testnet:7Hk3mRtQZvXp2nBw9Lj4K",
    "displayName": "John Doe",
    "avatarUrl": null,
    "createdAt": "2026-04-15T08:00:00Z"
  }
}

Get Current User

Retrieve the authenticated user profile.

GET /auth/me

Auth: JWT Bearer


// Response 200
{
  "user": {
    "id": "usr_7Hk3mRtQZv",
    "did": "did:solidus:testnet:7Hk3mRtQZvXp2nBw9Lj4K",
    "displayName": "John Doe",
    "bio": "Web3 builder",
    "avatarUrl": "https://identity.solidus.network/avatars/usr_7Hk3mRtQZv.jpg",
    "linkedAccounts": ["google", "github"],
    "credentialCount": 3,
    "createdAt": "2026-04-15T08:00:00Z"
  }
}

Redirect users to Google or GitHub for OAuth-based login. After authorization, the user is redirected to the callback URL with a JWT.

GET /auth/google — Redirects to Google OAuth

GET /auth/github — Redirects to GitHub OAuth

Credentials

List Credentials

Retrieve all verifiable credentials stored in the user’s wallet.

GET /credentials

Auth: JWT Bearer


// Response 200
{
  "credentials": [
    {
      "id": "vc_3Kn8rTpXm2",
      "type": ["VerifiableCredential", "KYCCredential"],
      "issuer": "did:solidus:issuer_9Xm4pLk",
      "issuerName": "Solidus Verify",
      "issuanceDate": "2026-05-07T14:25:30Z",
      "expirationDate": "2027-05-07T14:25:30Z",
      "status": "active",
      "claims": {
        "level": 2,
        "country": "US",
        "verifiedAt": "2026-05-07T14:25:30Z"
      }
    },
    {
      "id": "vc_8Rn3mKpWxT",
      "type": ["VerifiableCredential", "EmailCredential"],
      "issuer": "did:solidus:issuer_9Xm4pLk",
      "issuerName": "Solidus Identity",
      "issuanceDate": "2026-04-20T10:00:00Z",
      "expirationDate": "2027-04-20T10:00:00Z",
      "status": "active",
      "claims": {
        "email": "[email protected]",
        "verified": true
      }
    }
  ]
}

Get Credential

Retrieve a single credential with its verification status.

GET /credentials/:vcId

Auth: JWT Bearer


curl https://identity.solidus.network/v1/credentials/vc_3Kn8rTpXm2 \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..."


// Response 200
{
  "credential": {
    "id": "vc_3Kn8rTpXm2",
    "type": ["VerifiableCredential", "KYCCredential"],
    "issuer": "did:solidus:issuer_9Xm4pLk",
    "issuerName": "Solidus Verify",
    "issuanceDate": "2026-05-07T14:25:30Z",
    "expirationDate": "2027-05-07T14:25:30Z",
    "status": "active",
    "claims": {
      "level": 2,
      "country": "US",
      "verifiedAt": "2026-05-07T14:25:30Z"
    },
    "proof": {
      "type": "Ed25519Signature2020",
      "created": "2026-05-07T14:25:30Z",
      "verificationMethod": "did:solidus:issuer_9Xm4pLk#key-1",
      "proofValue": "z4MXy7Lk9Rn3..."
    },
    "onChainAnchor": "0x8a3f...b7c2"
  },
  "verification": {
    "valid": true,
    "checks": ["signature", "expiration", "revocation", "onChainAnchor"],
    "verifiedAt": "2026-05-07T14:30:00Z"
  }
}

Share credentials or specific claims with third parties. Users approve or deny sharing requests and can revoke access at any time.

Retrieve pending credential sharing requests from third parties.

GET /sharing/requests

Auth: JWT Bearer


// Response 200
{
  "requests": [
    {
      "id": "req_5Wn2kLpMxR",
      "requester": {
        "did": "did:solidus:app_4Tn7mLkPxR",
        "name": "DeFi Exchange",
        "domain": "exchange.example.com"
      },
      "requestedCredentials": ["KYCCredential"],
      "requestedClaims": ["level", "country"],
      "purpose": "Regulatory compliance for trading",
      "status": "pending",
      "createdAt": "2026-05-07T15:00:00Z",
      "expiresAt": "2026-05-08T15:00:00Z"
    }
  ]
}

Approve or deny a credential sharing request.

POST /sharing/requests/:requestId/respond

Auth: JWT Bearer


// Request body — approve with selective disclosure
{
  "action": "approve",
  "credentialId": "vc_3Kn8rTpXm2",
  "sharedClaims": ["level", "country"]
}


// Response 200
{
  "share": {
    "id": "shr_6Wn9pMkRxT",
    "requestId": "req_5Wn2kLpMxR",
    "credentialId": "vc_3Kn8rTpXm2",
    "sharedClaims": ["level", "country"],
    "requester": {
      "did": "did:solidus:app_4Tn7mLkPxR",
      "name": "DeFi Exchange"
    },
    "status": "active",
    "createdAt": "2026-05-07T15:05:00Z"
  }
}


// Request body — deny
{
  "action": "deny"
}


// Response 200
{
  "message": "Request denied"
}

List Active Shares

View all currently active credential shares.

GET /sharing/active

Auth: JWT Bearer


// Response 200
{
  "shares": [
    {
      "id": "shr_6Wn9pMkRxT",
      "credentialId": "vc_3Kn8rTpXm2",
      "credentialType": "KYCCredential",
      "sharedClaims": ["level", "country"],
      "requester": {
        "did": "did:solidus:app_4Tn7mLkPxR",
        "name": "DeFi Exchange",
        "domain": "exchange.example.com"
      },
      "status": "active",
      "createdAt": "2026-05-07T15:05:00Z"
    }
  ]
}

Revoke a previously approved credential share.

DELETE /sharing/active/:shareId

Auth: JWT Bearer


curl -X DELETE https://identity.solidus.network/v1/sharing/active/shr_6Wn9pMkRxT \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..."


// Response 200
{
  "message": "Share revoked"
}

Inbox

The inbox contains credential offers from issuers. Users can accept offers to add credentials to their wallet or decline them.

List Credential Offers

GET /inbox

Auth: JWT Bearer

Query Param	Type	Description
`status`	`string`	Filter by status: `pending`, `accepted`, `declined`, `expired`


// Response 200
{
  "offers": [
    {
      "id": "ofr_7Hk3mRtQZv",
      "issuer": {
        "did": "did:solidus:issuer_9Xm4pLk",
        "name": "Solidus Verify"
      },
      "credentialType": "KYCCredential",
      "preview": {
        "level": 2,
        "country": "US"
      },
      "status": "pending",
      "createdAt": "2026-05-07T14:25:30Z",
      "expiresAt": "2026-05-14T14:25:30Z"
    }
  ]
}

Accept Offer

Accept a credential offer and add it to your wallet.

POST /inbox/:offerId/accept

Auth: JWT Bearer


curl -X POST https://identity.solidus.network/v1/inbox/ofr_7Hk3mRtQZv/accept \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..."


// Response 200
{
  "credential": {
    "id": "vc_3Kn8rTpXm2",
    "type": ["VerifiableCredential", "KYCCredential"],
    "issuer": "did:solidus:issuer_9Xm4pLk",
    "status": "active",
    "createdAt": "2026-05-07T14:30:00Z"
  }
}

Decline Offer

Decline a credential offer.

POST /inbox/:offerId/decline

Auth: JWT Bearer


curl -X POST https://identity.solidus.network/v1/inbox/ofr_7Hk3mRtQZv/decline \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..."


// Response 200
{
  "message": "Offer declined"
}

Users

List Linked Accounts

Retrieve OAuth accounts linked to the authenticated user.

GET /users/me/linked-accounts

Auth: JWT Bearer


// Response 200
{
  "accounts": [
    {
      "provider": "google",
      "providerId": "118234567890",
      "email": "[email protected]",
      "name": "John Doe",
      "avatarUrl": "https://lh3.googleusercontent.com/...",
      "linkedAt": "2026-04-20T10:00:00Z"
    },
    {
      "provider": "github",
      "providerId": "12345678",
      "email": "[email protected]",
      "name": "johndoe",
      "avatarUrl": "https://avatars.githubusercontent.com/u/12345678",
      "linkedAt": "2026-04-22T14:00:00Z"
    }
  ]
}

Unlink Account

Remove a linked OAuth account.

DELETE /users/me/linked-accounts/:provider

Auth: JWT Bearer


curl -X DELETE https://identity.solidus.network/v1/users/me/linked-accounts/github \
  -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..."


// Response 200
{
  "message": "Account unlinked"
}

Get Public Profile

Retrieve the public profile of any user by their DID. This endpoint is public and requires no authentication.

GET /users/:did

Auth: None


curl https://identity.solidus.network/v1/users/did:solidus:testnet:7Hk3mRtQZvXp2nBw9Lj4K


// Response 200
{
  "user": {
    "did": "did:solidus:testnet:7Hk3mRtQZvXp2nBw9Lj4K",
    "displayName": "John Doe",
    "bio": "Web3 builder",
    "avatarUrl": "https://identity.solidus.network/avatars/usr_7Hk3mRtQZv.jpg",
    "createdAt": "2026-04-15T08:00:00Z"
  },
  "credentials": [
    {
      "type": "KYCCredential",
      "issuerName": "Solidus Verify",
      "level": 2,
      "issuedAt": "2026-05-07T14:25:30Z",
      "status": "active"
    }
  ]
}

Only credentials that the user has marked as publicly visible are included in the response.

Identity API

Authentication

Request Challenge

Verify Challenge

Get Current User

OAuth Login

Credentials

List Credentials

Get Credential

Sharing

List Sharing Requests

Respond to Sharing Request

List Active Shares

Revoke Share

Inbox

List Credential Offers

Accept Offer

Decline Offer

Users

List Linked Accounts

Unlink Account

Get Public Profile