OpenAPI Specification
openapi: 3.0.3
info:
title: Civic Customer pass 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: pass
description: Issue and manage Civic Passes
paths:
/pass:
post:
tags:
- pass
summary: List Civic Passes
description: Returns a list of all Civic Passes you have issued. Optionally filtered by the Civic Pass attributes. A pass may take a few seconds to a few minutes to show up here after issuing, depending on blockchain confirmation times.
operationId: listPass
requestBody:
content:
application/json:
schema:
type: object
properties:
limit:
type: number
default: 20
description: Number of records to return per page (used together with 'skip' for pagination)
skip:
type: number
default: 0
description: Number of records to skip (used together with 'limit' for pagination)
filter:
type: object
properties:
state:
$ref: '#/components/schemas/State'
walletAddress:
type: string
example: 4v4PL5bMZXXvQB3mvWPXLvqfJpjJmPRnPrmENnUESQQQ
responses:
200:
description: OK
content:
application/json:
schema:
type: object
properties:
records:
type: array
items:
type: object
$ref: '#/components/schemas/PassResponse'
security:
- pass_auth:
- write:token
- read:token
/pass/{chain}/{chainNetwork}:
post:
tags:
- pass
summary: Issue a Civic Pass
description: Issue a Civic Pass to a user's wallet. This action is asynchronous, i.e. it does not wait for the Civic Pass to be confirmed on-chain before returning.
operationId: issuePass
parameters:
- name: chain
in: path
description: The type of blockchain that the Civic Pass was issued on.
required: true
example: ethereum
schema:
$ref: '#/components/schemas/Chain'
- name: chainNetwork
in: path
description: The blockchain network
required: true
explode: true
example: sepolia
schema:
$ref: '#/components/schemas/ChainNetwork'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Wallet'
required: true
responses:
'202':
description: The issuance of the Civic Pass has been initiated.
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/PassResponse'
'401':
description: Unauthorized
'400':
description: Client error
security:
- pass_auth:
- write:token
- read:token
/pass/{chain}/{chainNetwork}/{wallet}:
get:
tags:
- pass
summary: Retrieve a Civic Pass.
description: Retrieve the full details about a Civic Pass you issued, including a log of all events associated with the specific pass. A pass may take a few seconds to a few minutes to show up here after issuing, depending on blockchain confirmation times.
operationId: getPass
parameters:
- name: chain
in: path
description: The blockchain type that the Civic Pass was issued on.
required: true
example: ethereum
schema:
$ref: '#/components/schemas/Chain'
- name: wallet
in: path
description: The user's wallet the Civic Pass was issued to.
required: true
example: '0xEA5Ce8F9C81b681876DC713d33371c3E262A5888'
schema:
type: string
- name: chainNetwork
in: path
description: The blockchain network
required: true
explode: true
example: sepolia
schema:
$ref: '#/components/schemas/ChainNetwork'
responses:
'200':
description: The Civic Pass associated with the given wallet.
content:
application/json:
schema:
$ref: '#/components/schemas/PassResponse'
'404':
description: No Civic pass is associatied with the given wallet.
security:
- pass_auth:
- write:token
- read:token
patch:
tags:
- pass
summary: Update a Civic Pass
description: Updates either the status or the expiration timestamp of a Civic Pass. This action is asynchronous, i.e. it does not wait for updates to be confirmed on-chain before returning. To immediately expire a pass, for example to force a user to refresh, set an expiration data a couple of second in the future.
operationId: patchPass
parameters:
- name: chain
in: path
description: The blockchain type that the Civic Pass was issued on.
required: true
example: ethereum
schema:
$ref: '#/components/schemas/Chain'
- name: wallet
in: path
description: The user's wallet the Civic Pass was issued to.
required: true
example: '0xEA5Ce8F9C81b681876DC713d33371c3E262A5888'
schema:
type: string
- name: chainNetwork
in: path
description: The blockchain network
required: true
explode: true
example: sepolia
schema:
$ref: '#/components/schemas/ChainNetwork'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateState'
required: true
responses:
'200':
description: ok
content:
application/json:
schema:
type: object
example:
status: ok
security:
- pass_auth:
- write:token
- read:token
delete:
tags:
- pass
summary: Revoke a Civic Pass
operationId: deletePass
description: Revoking a Civic Pass is **irreversible**. After the Civic Pass has been revoked, it is not possible to issue a new Civic Pass to the same {chain, wallet, network} combination.
parameters:
- name: chain
in: path
description: The blockchain type that the Civic Pass was issued on.
required: true
example: ethereum
schema:
$ref: '#/components/schemas/Chain'
- name: wallet
in: path
description: The user's wallet the Civic Pass was issued to.
required: true
example: '0xEA5Ce8F9C81b681876DC713d33371c3E262A5888'
schema:
type: string
- name: chainNetwork
in: path
description: The blockchain network
required: true
explode: true
example: sepolia
schema:
$ref: '#/components/schemas/ChainNetwork'
responses:
'200':
description: The revocation has been initiated.
security:
- pass_auth:
- write:token
- read:token
components:
schemas:
Chain:
type: string
description: The chain type
enum:
- solana
- ethereum
Wallet:
type: object
description: The wallet address to issue this token to
properties:
walletAddress:
type: string
example: '0xEA5Ce8F9C81b681876DC713d33371c3E262A5888'
State:
type: string
description: Available status
enum:
- ACTIVE
- REVOKED
- FROZEN
- REQUESTED
- REJECTED
ChainNetwork:
type: string
description: The chain network
enum:
- mainnet-beta
- devnet
- mainnet
- sepolia
- polygonAmoy
- polygonMainnet
- polygonZKEVM
- polygonZKEVMTestnet
- optimismSepolia
- optimismMainnet
- arbitrumSepolia
- arbitrumMainnet
- avalancheCChain
- avalancheCChainFuji
- xdcMainnet
- xdcApothem
- fantomMainnet
- fantomTestnet
- baseSepolia
- baseMainnet
- bscMainnet
- bscTestnet
- xlayerMainnet
- xlayerTestnet
- unichainMainnet
- unichainSepolia
- sonicMainnet
- sonicTestnet
PassResponse:
type: object
properties:
chain:
type: object
properties:
type:
$ref: '#/components/schemas/Chain'
network:
$ref: '#/components/schemas/ChainNetwork'
required:
- type
- network
gatekeeperNetwork:
description: The address of the [Gatekeeper Network](https://docs.civic.com/civic-pass/integrate/turnkey-integration/selecting-a-pass) this Civic Pass was issued for.
type: string
example: tgnuXXNMDLK8dy7Xm1TdeGyc95MDym4bvAQCwcW21Bf
walletAddress:
description: The wallet address that the Civic Pass is issued for.
type: string
example: 4v4PL5bMZXXvQB3mvWPXLvqfJpjJmPRnPrmENnUESQQQ
events:
description: Any action on a Civic Pass results in an event that is appended to this list.
type: array
items:
type: object
properties:
eventType:
type: string
enum:
- TOKEN_ISSUED_INITIATED
- TOKEN_ISSUED
- TOKEN_FROZEN_INITIATED
- TOKEN_FROZEN
- TOKEN_EXPIRY_CHANGED_INITIATED
- TOKEN_EXPIRY_CHANGED
- TOKEN_UNFROZEN_INITIATED
- TOKEN_UNFROZEN
- TOKEN_REVOKED_INITIATED
- TOKEN_REVOKED
timestamp:
type: number
example: 1677588899
transaction:
description: If the event has an associated chain transaction,its details are found here.
type: object
properties:
identifier:
type: string
example: 4GWazp2AqMmxkE6GKCoYf9rbgFL6eDTuMx9z7719eccSeCEYu9hiCvmcr9cK6ioiTUGZzvcWf6iB7fd3YCg39PT6
status:
type: string
enum:
- sent
- confirmed
- failed
required:
- identifier
required:
- eventType
- timestamp
id:
description: A unique, Civic-speficic identifier for the Civic Pass.
type: string
example: 63fdf96c58f1ae40a26a89be
onChainState:
type: string
enum:
- ACTIVE
- FROZEN
- REVOKED
state:
type: string
enum:
- ACTIVE
- FROZEN
- REVOKED
- REQUESTED
required:
- chain
- gatekeeperNetwork
- walletAddress
- events
- id
- onChainState
- state
UpdateState:
type: object
properties:
state:
$ref: '#/components/schemas/State'
expiryTimestamp:
description: The new expiration timestamp
example: 1677593295
type: number
securitySchemes:
pass_auth:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://auth0.civic.com/oauth/token
scopes: {}