Skip to main content

​
Action Encoding & Hashing

Actions scope s. When requesting these proofs, the user will prove they have only performed that specific action, for that specific RP and app once. Ultimately this is reflected with the computation of the which takes the rp_id, app_id, and action information as inputs (as well as a user-specific input not relevant here).
Each different action will result in a different .
Authenticators expect a pre-encoded action to be able to process requests. ID Kit already does this in the background, but for reference, this is how the action is encoded. 
    #[serde(Serialize, Deserialize)]
    struct WorldIdAction {
        /// The timestamp when the action will expire
        expires_at: u64,
        /// Arbitrary data to be included. Typically this would be a string value, which simply gets UTF-8 encoded.
        data: Vec<u8>,
        /// Description shown to the user when they are prompted to perform the action
        description: String,
    }

    impl WorldIdAction {
        pub fn encode(&self) -> String {
            let encoded_bytes = serde_json::to_vec(self).unwrap();
            let encoded_bytes = STANDARD.encode(&json_bytes);
            format!("act_{}", encoded_bytes)
        }
    }
The authenticator uses the encoded action to:
  • Display the description to the user.
  • Compute the hash of the action and use it in the proof (by removing the act_ prefix and using the base 64 decoded bytes as the input).

​
Authenticator Requests & Responses

This section describes how authenticators receive and respond to requests from RPs. This also reflects what is implemented in the . The authenticator receives a request from an RP in the following format.

​
Request Schema

​
id
string
required
A unique identifier for this request.
​
version
number
required
The version of the request. Must equal to 1.
​
created_at
string
The date and time the request was created.
​
expires_at
string
required
The date and time the request will expire.
​
rp_id
string
required
The ID of the RP requesting the proof. Must be registered in the .
​
app_id
string
required
The ID for the app requesting the proof.
​
encoded_action
string
required
The action being performed. See Action Encoding & Hashing for more details.
​
requests
array
required
The credentials being requested for verification.
  • type (required): The type of credential being requested.
  • signal: An optional commitment which the user signs.
​
constraints
object
Boolean expression over credential types.
  • Use one of all or any at each level.
  • Values are arrays of credential type strings and/or nested constraint objects, with at most one level of nesting.

​
Request Examples

{
  "id": "req_18c0f7f03e7d",
  "version": 1,
  "created_at": "2025-09-03T17:33:12Z",
  "expires_at": "2025-09-03T17:38:12Z",
  "rp_id": "rp_0000000000000000000000000000000000001",
  "app_id": "app_123",
  "encoded_action": "act_0000000000000000000000000000000000001",
  "requests": [
    {
      "type": "gov-id",
      "signal": "abcd-efgh-ijkl"
    }
  ]
}

​
Constraint Evaluation

When using the any constraint, the order of credential types in the array determines priority order. The authenticator will attempt to provide the first available credential type in the list. If that credential is not available, it will fall back to the next type in the array, and so on.
Priority ordering only applies to any constraints. For all constraints, all specified credential types must be provided regardless of order.
Example: 
{
  "constraints": { "any": ["orb", "document"] }
}
In this case:
  • If the user has an orb credential, the authenticator will provide it
  • If the user does not have an orb credential but has a document credential, the authenticator will provide the document instead
  • The orb credential type has priority over document
This priority mechanism allows RPs to request their preferred credential type while still accepting fallback options if the preferred type is unavailable.

​
Response Schema

​
id
string
required
The request identifier this response corresponds to.
​
version
number
required
The response version. Must equal to 1.
​
responses
array
required
Per-credential results. Each item contains:
  • type (string, required): Credential type this item refers to.
  • proof (string): Proof payload when applicable (e.g., uniqueness proof).
  • nullifier (string): The computed for the action when applicable.
  • session_id (string): Session identifier if a session is established.
  • error (string): Present if the credential could not be provided.
Success is implicit. If a response item is present without an error, the credential was provided successfully. Do not include a success boolean.

​
Response Examples

{
"id": "req_18c0f7f03e7d",
"version": 1,
"responses": [
    {
        "type": "orb",
        "proof": "0x0000000000000000000000000000000000000000000000000000000000000000000000000",
        "nullifier": "nil_00000000000000000000000000000000000000000000000001"
    }
]
}

​
Paired Request/Response Examples

A request is considered successful if the provided response items satisfy the declared constraints. Items with an error do not satisfy constraints.
{
  "id": "req_18c0f7f03e7d",
  "version": 1,
  "created_at": "2025-09-03T17:33:12Z",
  "expires_at": "2025-09-03T17:38:12Z",
  "rp_id": "rp_0000000000000000000000000000000000001",
  "app_id": "app_123",
  "encoded_action": "act_0000000000000000000000000000000000001",
  "requests": [
    { "type": "orb", "signal": "abcd-efgh-ijkl" },
    { "type": "passport", "signal": "abcd-efgh-ijkl" }
  ],
  "constraints": { "all": ["orb", "passport"] }
}

{
  "id": "req_18c0f7f03e7d",
  "version": 1,
  "responses": [
    {
      "type": "orb",
      "proof": "0x0000000000000000000000000000000000000000000000000000000000000000000000000",
      "nullifier": "nil_00000000000000000000000000000000000000000000000001"
    },
    {
      "type": "passport",
      "proof": "0x0000000000000000000000000000000000000000000000000000000000000000000000000",
      "nullifier": "nil_00000000000000000000000000000000000000000000000001"
    }
  ]
}