Ctrlk
ExplorerFaucetBridgeDeveloper PortalWhitepaperDashboard
For the complete documentation index, see llms.txt. This page is also available as Markdown.

API Reference

get
/oauth/authorize
Query parameters
client_idstringRequired
redirect_uristringRequired
response_typeconst: codeRequired
scopestringRequired
statestringOptional
code_challengestringRequired
code_challenge_methodconst: S256Required
authorization_idstringOptional
login_hintstringOptional
localestringOptional
noncestringOptional
Responses
200Success
application/json
get/oauth/authorize
GET /oauth/authorize?client_id=text&redirect_uri=text&response_type=null&scope=text&code_challenge=text&code_challenge_method=null HTTP/1.1
Host: api.sandbox.humanity.org/
Accept: */*
200Success
post
/oauth/token
Body
or
Responses
200Success
application/json
access_tokenstringRequired
token_typeconst: BearerRequired
expires_innumberRequired
scopestringRequired
granted_scopesstring[]Required
authorization_idstringRequired
app_scoped_user_idstringRequired
issued_atstringOptional
refresh_tokenstringOptional
refresh_token_expires_innumberOptional
refresh_issued_atstringOptional
id_tokenstringOptional
post/oauth/token
POST /oauth/token HTTP/1.1
Host: api.sandbox.humanity.org/
Content-Type: application/json
Accept: */*
Content-Length: 97

{
  "grant_type": null,
  "code": "text",
  "redirect_uri": "text",
  "client_id": "text",
  "code_verifier": "text"
}
200Success
{
  "access_token": "text",
  "token_type": null,
  "expires_in": 1,
  "scope": "text",
  "granted_scopes": [
    "text"
  ],
  "authorization_id": "text",
  "app_scoped_user_id": "text",
  "issued_at": "text",
  "refresh_token": "text",
  "refresh_token_expires_in": 1,
  "refresh_issued_at": "text",
  "id_token": "text"
}
post
/oauth/client/user-token
Body
client_idstringRequired
client_secretstringRequired
identifierstringOptional
user_idstringOptional
emailstringOptional
evm_addressstringOptional
Responses
200Success
application/json
access_tokenstringRequired
token_typeconst: BearerRequired
expires_innumberRequired
issued_atstringRequired
user_idstringRequired
client_idstringRequired
authorization_idstringRequired
scopesstring[]Required
post/oauth/client/user-token
POST /oauth/client/user-token HTTP/1.1
Host: api.sandbox.humanity.org/
Content-Type: application/json
Accept: */*
Content-Length: 116

{
  "client_id": "text",
  "client_secret": "text",
  "identifier": "text",
  "user_id": "text",
  "email": "text",
  "evm_address": "text"
}
200Success
{
  "access_token": "text",
  "token_type": null,
  "expires_in": 1,
  "issued_at": "text",
  "user_id": "text",
  "client_id": "text",
  "authorization_id": "text",
  "scopes": [
    "text"
  ]
}
get
/oauth/authorize/context
Query parameters
authorization_idstringRequired
Responses
200Success
application/json
authorization_idstringRequired
client_idstringRequired
user_idstringRequired
app_scoped_user_idstringRequired
statusone ofRequired
const: pending_adminOptional
or
const: approvedOptional
or
const: deniedOptional
or
const: revokedOptional
or
const: consumedOptional
redirect_uristringRequired
statestringOptional
requested_scopesstring[]Required
granted_scopesstring[]Optional
codestringOptional
code_expires_atstringOptional
noncestringOptional
get/oauth/authorize/context
GET /oauth/authorize/context?authorization_id=text HTTP/1.1
Host: api.sandbox.humanity.org/
Accept: */*
200Success
{
  "authorization_id": "text",
  "client_id": "text",
  "user_id": "text",
  "app_scoped_user_id": "text",
  "status": null,
  "redirect_uri": "text",
  "state": "text",
  "requested_scopes": [
    "text"
  ],
  "granted_scopes": [
    "text"
  ],
  "code": "text",
  "code_expires_at": "text",
  "nonce": "text",
  "application": {
    "client_id": "text",
    "name": "text",
    "organization_id": "text",
    "status": null,
    "redirect_uris": [
      "text"
    ],
    "created_by_user_id": "text",
    "created_at": "text",
    "updated_at": "text",
    "revoked_at": "text"
  },
  "scopes": [
    {
      "id": "text",
      "display_name": "text",
      "description": "text",
      "category": "text",
      "implied_scopes": [
        "text"
      ],
      "is_default": true
    }
  ],
  "metadata": {
    "created_at": "text",
    "updated_at": "text",
    "approved_at": "text",
    "revoked_at": "text",
    "last_token_issued_at": "text"
  },
  "policy": {
    "requires_palm_verification": true,
    "preset_cache_ttl_seconds": 1
  }
}
get
/oauth/authorize/result
Query parameters
authorization_idstringRequired
Responses
200Success
application/json
get/oauth/authorize/result
GET /oauth/authorize/result?authorization_id=text HTTP/1.1
Host: api.sandbox.humanity.org/
Accept: */*
200Success
post
/oauth/revoke
Body
tokenstringOptional
tokensstring[]Optional
token_type_hintone ofOptional
const: authorizationOptional
or
const: refresh_tokenOptional
or
const: access_tokenOptional
authorization_idstringOptional
cascadeone ofOptional
const: 0Optional
or
const: trueOptional
or
const: falseOptional
or
const: 1Optional
or
booleanOptional
client_idstringOptional
Responses
200Success
application/json
revokedbooleanRequired
revoked_countnumberRequired
post/oauth/revoke
POST /oauth/revoke HTTP/1.1
Host: api.sandbox.humanity.org/
Content-Type: application/json
Accept: */*
Content-Length: 117

{
  "token": "text",
  "tokens": [
    "text"
  ],
  "token_type_hint": null,
  "authorization_id": "text",
  "cascade": null,
  "client_id": "text"
}
200Success
{
  "revoked": true,
  "revoked_count": 1,
  "details": [
    {
      "subject": null,
      "token_type": null,
      "authorization_id": "text",
      "client_id": "text",
      "user_id": "text",
      "status": null,
      "reason": "text"
    }
  ]
}
post
/oauth/authorize/approve
Body
authorization_idstringRequired
scopesstring[]Optional
Responses
200Success
application/json
authorization_idstringRequired
statusconst: approvedRequired
codestringRequired
code_expires_atstringRequired
scopesstring[]Required
granted_scopesstring[]Required
app_scoped_user_idstringRequired
organization_idstringRequired
statestringOptional
redirect_uristringRequired
client_idstringRequired
post/oauth/authorize/approve
POST /oauth/authorize/approve HTTP/1.1
Host: api.sandbox.humanity.org/
Content-Type: application/json
Accept: */*
Content-Length: 45

{
  "authorization_id": "text",
  "scopes": [
    "text"
  ]
}
200Success
{
  "authorization_id": "text",
  "status": null,
  "code": "text",
  "code_expires_at": "text",
  "scopes": [
    "text"
  ],
  "granted_scopes": [
    "text"
  ],
  "app_scoped_user_id": "text",
  "organization_id": "text",
  "state": "text",
  "redirect_uri": "text",
  "client_id": "text"
}
get
/v2/userinfo
Responses
200Success
application/json
substringRequired
issstringRequired
audstringRequired
authorization_idstringRequired
scopesstring[]Required
updated_atstringOptional
humanity_idstring · nullableOptional
wallet_addressstring · nullableOptional
emailstring · nullableOptional
email_verifiedbooleanOptional
get/v2/userinfo
GET /v2/userinfo HTTP/1.1
Host: api.sandbox.humanity.org/
Accept: */*
200Success
{
  "sub": "text",
  "iss": "text",
  "aud": "text",
  "authorization_id": "text",
  "scopes": [
    "text"
  ],
  "updated_at": "text",
  "humanity_id": null,
  "wallet_address": null,
  "email": null,
  "email_verified": true
}
get
/v2/developer/organization

Get the organization for the authenticated developer

Responses
200Success
application/json
idstringRequired
namestringRequired
ownerIdstring · nullableRequired
isOwnerbooleanRequired
get/v2/developer/organization
GET /v2/developer/organization HTTP/1.1
Host: api.sandbox.humanity.org/
Accept: */*
200Success
{
  "id": "text",
  "name": "text",
  "ownerId": null,
  "isOwner": true
}
put
/v2/developer/organization

Update the organization name (owner only)

Body
namestringRequired
Responses
200Success
application/json
idstringRequired
namestringRequired
ownerIdstring · nullableRequired
isOwnerbooleanRequired
put/v2/developer/organization
PUT /v2/developer/organization HTTP/1.1
Host: api.sandbox.humanity.org/
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "name": "text"
}
200Success
{
  "id": "text",
  "name": "text",
  "ownerId": null,
  "isOwner": true
}
get
/v2/presets/{preset_name}
Path parameters
preset_namestringRequired
Responses
200Success
application/json
presetone ofRequired
const: humanity_uuidOptional
or
const: humanity_scoreOptional
or
const: is_humanOptional
or
const: country_of_residenceOptional
or
const: ageOptional
or
const: date_of_birthOptional
or
const: residency_regionOptional
or
const: age_over_18Optional
or
const: nationalityOptional
or
const: emailOptional
or
const: phoneOptional
or
const: age_over_21Optional
or
const: social_accountsOptional
or
const: wallet_addressOptional
or
const: primary_wallet_addressOptional
or
const: address_postal_codeOptional
or
const: legal_nameOptional
or
const: address_fullOptional
or
const: document_countryOptional
or
const: document_expiry_dateOptional
or
const: document_numberOptional
or
const: net_worth_totalOptional
or
const: bank_balance_totalOptional
or
const: loan_balance_totalOptional
or
const: kyc_passedOptional
or
const: kyc_last_updated_atOptional
or
const: net_worth_above_10kOptional
or
const: net_worth_above_100kOptional
or
const: google_connectedOptional
or
const: linkedin_connectedOptional
or
const: facebook_connectedOptional
or
const: twitter_connectedOptional
or
const: discord_connectedOptional
or
const: github_connectedOptional
or
const: telegram_connectedOptional
or
const: palm_verifiedOptional
or
const: humanity_userOptional
or
const: proof_of_assetsOptional
or
const: proof_of_investmentsOptional
or
const: proof_of_mortgageOptional
or
const: proof_of_residencyOptional
or
const: proof_of_retirementOptional
valueanyRequired
statusone ofRequired
const: validOptional
or
const: pendingOptional
or
const: expiredOptional
or
const: unavailableOptional
expires_atstringRequired
verified_atstringOptional
get/v2/presets/{preset_name}
GET /v2/presets/{preset_name} HTTP/1.1
Host: api.sandbox.humanity.org/
Accept: */*
200Success
{
  "preset": null,
  "value": null,
  "status": null,
  "expires_at": "text",
  "verified_at": "text",
  "evidence": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
post
/v2/presets/batch
Body
Responses
200Success
application/json
post/v2/presets/batch
POST /v2/presets/batch HTTP/1.1
Host: api.sandbox.humanity.org/
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "presets": [
    null
  ]
}
200Success
{
  "results": [
    {
      "preset": null,
      "value": null,
      "status": null,
      "expires_at": "text",
      "verified_at": "text",
      "evidence": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "errors": [
    {
      "preset": null,
      "error": {
        "error": "text",
        "error_code": null,
        "error_description": "text",
        "error_subcode": "text",
        "context": {
          "ANY_ADDITIONAL_PROPERTY": null
        }
      }
    }
  ]
}
get
/v2/presets
Responses
200Success
application/json
get/v2/presets
GET /v2/presets HTTP/1.1
Host: api.sandbox.humanity.org/
Accept: */*
200Success
{
  "presets": [
    {
      "name": null,
      "scope": null,
      "category": null,
      "description": "text",
      "consentText": "text",
      "type": null,
      "sensitivity": null,
      "derived": true,
      "parentField": null
    }
  ]
}

Evaluate a query against the authenticated user's credentials

post
/v2/queries/evaluate

Evaluate a query against the authenticated user's credentials. This endpoint allows declarative queries to check user claims.

Body

Request body for query evaluation.

queryone ofRequired

The query to evaluate. Can be a simple check or compound policy.

or
or
Responses
200

Query evaluation result

application/json
or
post/v2/queries/evaluate
POST /v2/queries/evaluate HTTP/1.1
Host: api.sandbox.humanity.org/
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "query": {
    "check": {
      "claim": "text",
      "operator": null,
      "value": null
    }
  }
}
200

Query evaluation result

{
  "type": null,
  "passed": true,
  "evaluatedAt": "text",
  "evidence": {
    "claimsUsed": [
      {
        "path": "text",
        "value": null,
        "credentialId": "text",
        "source": "text"
      }
    ],
    "checkResults": [
      {
        "claim": "text",
        "operator": "text",
        "expectedValue": null,
        "actualValue": null,
        "passed": true
      }
    ]
  },
  "expiresAt": "text"
}
get
/v2/authorizations
Query parameters
statusone ofOptional
const: revokedOptional
or
const: activeOptional
updated_sincestringOptional
limitnumberOptional
Responses
200Success
application/json
last_modifiedstringOptional
has_morebooleanOptional
get/v2/authorizations
GET /v2/authorizations HTTP/1.1
Host: api.sandbox.humanity.org/
Accept: */*
200Success
{
  "items": [
    {
      "authorization_id": "text",
      "organization_id": "text",
      "app_scoped_user_id": "text",
      "status": null,
      "updated_at": "text"
    }
  ],
  "last_modified": "text",
  "has_more": true
}
get
/.well-known/hp-configuration
Responses
200Success
application/json
issuerstringRequired
authorization_endpointstringRequired
token_endpointstringRequired
revoke_endpointstringRequired
userinfo_endpointstringRequired
jwks_uristringRequired
presets_endpointstringRequired
presets_batch_endpointstringRequired
credentials_endpointstringRequired
authorizations_endpointstringRequired
hp_configuration_endpointstringRequired
scopes_supportedstring[]Required
grant_types_supportedstring[]Required
code_challenge_methods_supportedstring[]Required
response_types_supportedstring[]Required
token_endpoint_auth_methods_supportedstring[]Required
subject_types_supportedstring[]Required
claim_types_supportedstring[]Required
claims_supportedstring[]Required
id_token_signing_alg_values_supportedstring[]Required
rate_limit_defaultnumberRequired
rate_limit_unitstringRequired
get/.well-known/hp-configuration
GET /.well-known/hp-configuration HTTP/1.1
Host: api.sandbox.humanity.org/
Accept: */*
200Success
{
  "issuer": "text",
  "authorization_endpoint": "text",
  "token_endpoint": "text",
  "revoke_endpoint": "text",
  "userinfo_endpoint": "text",
  "jwks_uri": "text",
  "presets_endpoint": "text",
  "presets_batch_endpoint": "text",
  "credentials_endpoint": "text",
  "authorizations_endpoint": "text",
  "hp_configuration_endpoint": "text",
  "scopes_supported": [
    "text"
  ],
  "scopes_catalog": [
    {
      "id": "text",
      "display_name": "text",
      "description": "text",
      "category": "text",
      "implied_scopes": [
        "text"
      ],
      "is_default": true
    }
  ],
  "grant_types_supported": [
    "text"
  ],
  "code_challenge_methods_supported": [
    "text"
  ],
  "response_types_supported": [
    "text"
  ],
  "token_endpoint_auth_methods_supported": [
    "text"
  ],
  "subject_types_supported": [
    "text"
  ],
  "claim_types_supported": [
    "text"
  ],
  "claims_supported": [
    "text"
  ],
  "id_token_signing_alg_values_supported": [
    "text"
  ],
  "presets_available": [
    {
      "name": null,
      "scope": "text",
      "type": null,
      "description": "text",
      "consent_text": "text"
    }
  ],
  "rate_limit_default": 1,
  "rate_limit_unit": "text"
}
get
/.well-known/openid-configuration
Responses
200Success
application/json
issuerstringRequired
authorization_endpointstringRequired
token_endpointstringRequired
userinfo_endpointstringRequired
jwks_uristringRequired
response_types_supportedstring[]Required
grant_types_supportedstring[]Required
scopes_supportedstring[]Required
code_challenge_methods_supportedstring[]Required
token_endpoint_auth_methods_supportedstring[]Required
subject_types_supportedstring[]Required
claim_types_supportedstring[]Required
claims_supportedstring[]Required
id_token_signing_alg_values_supportedstring[]Required
revocation_endpointstringRequired
revocation_endpoint_auth_methods_supportedstring[]Optional
get/.well-known/openid-configuration
GET /.well-known/openid-configuration HTTP/1.1
Host: api.sandbox.humanity.org/
Accept: */*
200Success
{
  "issuer": "text",
  "authorization_endpoint": "text",
  "token_endpoint": "text",
  "userinfo_endpoint": "text",
  "jwks_uri": "text",
  "response_types_supported": [
    "text"
  ],
  "grant_types_supported": [
    "text"
  ],
  "scopes_supported": [
    "text"
  ],
  "code_challenge_methods_supported": [
    "text"
  ],
  "token_endpoint_auth_methods_supported": [
    "text"
  ],
  "subject_types_supported": [
    "text"
  ],
  "claim_types_supported": [
    "text"
  ],
  "claims_supported": [
    "text"
  ],
  "id_token_signing_alg_values_supported": [
    "text"
  ],
  "revocation_endpoint": "text",
  "revocation_endpoint_auth_methods_supported": [
    "text"
  ]
}
get
/.well-known/jwks.json
Responses
200Success
application/json
get/.well-known/jwks.json
GET /.well-known/jwks.json HTTP/1.1
Host: api.sandbox.humanity.org/
Accept: */*
200Success
{
  "keys": [
    {
      "kty": "text",
      "use": null,
      "kid": "text",
      "alg": "text",
      "n": "text",
      "e": "text"
    }
  ]
}
get
/health
Responses
200Success
application/json
statusconst: okRequired
uptimenumberRequired
versionstringRequired
commitstring · nullableRequired
timestampstringRequired
get/health
GET /health HTTP/1.1
Host: api.sandbox.humanity.org/
Accept: */*
200Success
{
  "status": null,
  "uptime": 1,
  "version": "text",
  "commit": null,
  "timestamp": "text"
}
get
/ready
Responses
200Success
application/json
statusone ofRequired
const: readyOptional
or
const: not_readyOptional
get/ready
GET /ready HTTP/1.1
Host: api.sandbox.humanity.org/
Accept: */*
200Success
{
  "status": null,
  "checks": [
    {
      "name": "text",
      "ok": true,
      "details": {
        "ANY_ADDITIONAL_PROPERTY": null
      }
    }
  ]
}
PreviousResources
NextModels

Last updated