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: {}