Claims reference · pasby docs

Every ID data claim key, response shape, encryption, and copy-paste request examples.

Identity data in pasby is exposed as claims: dot-notation strings you request at flow start. The user consents on the pasby app or identification UI; only approved keys appear in the result.

Request claims

Pass exact strings in the claims array on:

Identification (POST /api/v2/identification/*)
OIDC start session (POST /api/v1/oidc/kipindi)

{
  "action": "login",
  "claims": ["naming.given", "naming.family", "contact.email"],
  "payload": "Sign in to your application"
}

See Scopes for which endpoints your app may call, and Actions for login, signup, and link.

Claim catalog

Bio

Claim	Description
`bio.birthplace`	Place of birth
`bio.birthdate`	Date of birth
`bio.gender`	Gender
`bio.maritalstatus`	Marital status
`bio.birthnumber`	Birth registration number

Contact

Claim	Description
`contact.email`	Email address
`contact.emailVerified`	Whether email is verified
`contact.phone`	Phone number
`contact.phoneVerified`	Whether phone is verified

Address

Claim	Description
`address.city`	City
`address.postcode`	Postal code
`address.country`	Country
`address.place`	Place name
`address.formatted`	Full formatted address
`address.longitude`	Longitude
`address.latitude`	Latitude

Naming

Claim	Description
`naming.family`	Family / surname name
`naming.given`	Given / first name
`naming.title`	Title
`naming.name`	Full display name
`naming.middle`	Middle name
`naming.titlePrefix`	Title prefix (e.g. Dr.)
`naming.titleSuffix`	Title suffix
`naming.nickname`	Nickname

Nationality

Claim	Description
`nationality.nationalities`	Nationalities held
`nationality.pep`	Politically exposed person flag
`nationality.primary`	Primary nationality
`nationality.residence`	Country of residence
`nationality.watchListed`	Watch-list indicator

ID cards & financial

Claim	Description
`idcards.passport`	Passport details
`financial.bvn`	Bank verification number
`financial.bvnBank`	BVN issuing bank
`financial.bvnLevel`	BVN verification level
`financial.bvnIAT`	BVN identity assurance timestamp

Medical and education claims exist for specially provisioned apps. The table above covers typical commercial integrations.

Flow model fields

When you create an identification flow, the data.request object includes the claims you asked for under acquireClaims:

{
  "status": "successful",
  "reason": "Identification request created",
  "data": {
    "link": "https://open.pasby.africa/app/?mode=identification&id=req_…",
    "request": {
      "id": "req_1714661447-NUkY",
      "mode": "identification",
      "action": "signup",
      "acquireClaims": [
        "naming.family",
        "naming.given",
        "contact.email"
      ],
      "signature": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
    }
  }
}

Field reference: Identification flow model.

Encrypted claims on flow ping

Completed identification flows return encrypted claim values on POST /api/v2/flow/ping. Decrypt with your app's RSA private key from the pasby console (communication keys).

Raw ping excerpt:

{
  "data": {
    "request": {
      "claims": {
        "contact": {
          "email": "y6l/srG+g/2l2QinsjXxnn4MxY0cTzIDFiRrChjtSIl/…"
        },
        "naming": {
          "family": "SsF83HO/6g6+Sf+6n0nl3NhSJoEsMYYy5KMuBkIrtH33pD+…",
          "given": "LqDr6DjnleWbPLESTCd8t9ttuwFL4fwiW1R3hS5Q/o/jk/7K8E1P2K…"
        }
      }
    }
  }
}

After decryption:

{
  "claims": {
    "contact": { "email": "john.doe@example.com" },
    "naming": { "family": "Doe", "given": "John" }
  }
}

Full walkthrough: Handling encrypted claims.

npm install node-jsencrypt

import JSEncrypt from "node-jsencrypt";

function decryptClaim(privateKeyPem, ciphertext) {
  const crypt = new JSEncrypt();
  crypt.setKey(privateKeyPem);
  return crypt.decrypt(ciphertext);
}

// Example: decrypt contact.email from ping payload
const email = decryptClaim(
  process.env.PASBY_APP_PRIVATE_KEY,
  claims.contact.email,
);

Sample implementation: Finsel-DGI/SampleCode — pasby.ts.

OIDC resource response

For OIDC, approved claims are returned in data.claims (structure mirrors the nested groups above). Sandbox apps may receive synthetic test data.

Quickstart — first request with claims[]
Errors — validation when claims are missing or invalid
Credentials — keys and communication PEM files