openapi: 3.0.3 info: title: Civic Customer pass piirequest API description: "The APIs described below enable Civic customers to issue and manage the Civic Pass for their dApp. To learn more about Civic Passes and their fundamentals, please refer to the main [documentation](https://docs.civic.com/).\n\n# Terminology\n\nIn the Customer API, the term `chain` refers to a blockchain programming model and the term `chainNetwork` to a network of that chain. For example, a \"Layer 2\" Ethereum network like Polygon is represented as `/pass/ethereum/polygonMainnet`.\n\n# Supported Chains\n\nThe Customer API supports the following chains and chain networks:\n- `solana:mainnet-beta`\n- `solana:devnet`\n- `ethereum:mainnet`\n- `ethereum:sepolia`\n- `ethereum:polygonAmoy`\n- `ethereum:polygonMainnet`\n- `ethereum:polygonZKEVM`\n- `ethereum:polygonZKEVMTestnet`\n- `ethereum:optimismSepolia`\n- `ethereum:optimismMainnet`\n- `ethereum:arbitrumSepolia`\n- `ethereum:arbitrumMainnet`\n- `ethereum:avalancheCChain`\n- `ethereum:avalancheCChainFuji`\n- `ethereum:xdcMainnet`\n- `ethereum:xdcApothem`\n- `ethereum:fantomMainnet`\n- `ethereum:fantomTestnet`\n- `ethereum:baseSepolia`\n- `ethereum:baseMainnet`\n- `ethereum:bscMainnet`\n- `ethereum:bscTestnet`\n- `ethereum:xlayerMainnet`\n- `ethereum:xlayerTestnet`\n- `ethereum:unichainMainnet`\n- `ethereum:unichainSepolia`\n- `ethereum:sonicMainnet`\n- `ethereum:sonicTestnet`\n\nIf your blockchain of choice is not listed above, feel free to reach out to us for more info on when support for your chain is planned.\n\n# Authentication\nAuthentication follows the [OAuth standard](https://oauth.net/2/). The Civic authentication endpoint is `https://auth0.civic.com/oauth/token`. The `grant_type` to request is `client_credentials`.\n\nTo manage API authentication we recommend using one of the available [OAuth libraries](https://oauth.net/code/) for your platform.\n\n# Try it out!\nYou can try out the Civic Pass Customer API by using the following demo credentials to generate an auth token:\n- `client_id: dtVTGsKUlkPQ8UXKqSskS1HqNI3hERHT`,\n- `client_secret: 7DT722BjNlXUp8HVaV_ZjHzopq2Tr12doGB8sBYC-vhPo3Eh0HoidLVATFbxmwZ1`\n\nPlease keep in mind that these are shared credentials, i.e. others have access to the same Civic Passes and can for example freeze them.\n\nThe `gatekeeperNetwork` : `tgnuXXNMDLK8dy7Xm1TdeGyc95MDym4bvAQCwcW21Bf` should be used with these credentials. That is Civic's sandbox pass.\n\nThe demo pass is only supported on testnets. The current list is:\n - `solana:devnet`\n - `ethereum:polygonAmoy`\n - `ethereum:sepolia`\n - `ethereum:baseSepolia`\n - `ethereum:arbitrumSepolia`\n - `ethereum:optimismSepolia`\n - `ethereum:bscTestnet`\n - `ethereum:xdcApothem`\n - `ethereum:xlayerTestnet`\n - `ethereum:avalancheCChainFuji`\n - `ethereum:unichainSepolia`\n - `ethereum:sonicTestnet`" termsOfService: https://www.civic.com/legal/terms-of-service-civic-pass-v1/ contact: email: devsupport@civic.com version: 1.0.0 servers: - url: https://api.civic.com/partner tags: - name: piirequest description: Get user PII and approve / reject receipt of PII paths: /piirequest/{scopeRequestId}: get: tags: - piirequest summary: Get the user's PII using a ScopeRequestId provided by Civic operationId: getPii description: After the user's PII has been delivered to Civic, we give you an ID (scopeRequestId) that can be used to retrieve the user's PII before issuing the Civic Pass. parameters: - name: scopeRequestId in: path description: The ID that was provided to you by Civic after the user has submitted their PII required: true example: 9a7a77af-a58e-4e54-83c9-5daa96ccbf11 schema: type: string responses: 200: description: OK content: application/json: schema: $ref: '#/components/schemas/GetPiiResponse' /piirequest/{scopeRequestId}/status: put: tags: - piirequest summary: Approve or Reject receipt of PII, to allow or block issuance of the user's Civic Pass. operationId: updatePiiReceipt description: After you reviewed the user's PII returned by the GET /piirequest/{scopeRequestId} endpoint, you can approve or reject the user's Civic Pass by calling this endpoint. parameters: - name: scopeRequestId in: path description: The ID that was provided to you by Civic after the user has submitted their PII required: true example: 9a7a77af-a58e-4e54-83c9-5daa96ccbf11 schema: type: string - name: status in: body description: Set this to 'partner-pass' to approve the issuance of the user's Civic Pass, or 'partner-fail' to reject it. schema: type: string enum: - partner-pass - partner-fail requestBody: content: application/json: schema: type: object properties: status: type: string enum: - partner-pass - partner-fail description: Whether to approve (pass) or reject (fail) the issuance of the user's Civic Pass. required: - status responses: 200: description: OK components: schemas: GetPiiResponse: type: object properties: status: description: The status of this PII request. The PII can be retrieved once this has reached 'verification-success' type: string enum: - awaiting-user - user-acknowledged - verification-success - verification-failed - user-cancelled - partner-pass - partner-fail verifiedInformation: type: object description: A set of all the user's PII that Civic could verify. The exact set of fields will differ depending on your pass configuration. example: email: user@example.com documentType: passport issueCountry: GBR name: First Middle Last dateOfBirth: '1990-01-01' dateOfExpiry: '2035-05-28' documentNumber: 0123456789 address: '0x1234abcd' links: type: array description: A list of the evidence item URLs collected from the user. items: type: object properties: rel: type: string example: idDocumentFront href: type: string example: https://api.civic.com/partner/piirequest/9a7a77af-a58e-4e54-83c9-5daa96ccbf11 securitySchemes: pass_auth: type: oauth2 flows: clientCredentials: tokenUrl: https://auth0.civic.com/oauth/token scopes: {}