diff --git a/swagger.yaml b/swagger.yaml index 18782cb..282dc40 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -1,52 +1,36 @@ openapi: 3.0.3 info: - title: Civic Pass API + title: Civic Pass Customer 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/). - + # Terminology - - In the Civic Pass 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 polygonMainnet is represented as `/pass/ethereum/polygonMainnet`. - + + In 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/matic`. + # Supported Chains - - The Civic Pass API supports the following chains and chain networks: + + The Customer API supports the following chains and chain networks: - `solana/mainnet-beta` - `solana/devnet` - `ethereum/homestead` - - `ethereum/arbitrumGoerli` - - `ethereum/arbitrumMainnet` - - `ethereum/arbitrumSepolia` + - `ethereum/sepolia` - `ethereum/goerli` - - `ethereum/avalancheCChain` - - `ethereum/avalancheCChainFuji` - - `ethereum/baseSepolia` - - `ethereum/baseMainnet` - - `ethereum/fantomMainnet` - - `ethereum/fantomTestnet` - - `ethereum/mainnet` - - `ethereum/optimismGoerli` - - `ethereum/optimismMainnet` - - `ethereum/polygonMainnet` - - `ethereum/polygonMumbai` - - `ethereum/polygonZKEVM` - - `ethereum/polygonZKEVMTestnet` - - `ethereum/xdcMainnet` - - `ethereum/xdcApothem` - + - `ethereum/matic` + If 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. - + # Authentication Authentication follows the [OAuth standard](https://oauth.net/2/). The Civic authentication endpoint is `https://auth.civic.com/oauth/token`. The `grant_type` to request is `client_credentials`. - + To manage API authentication we recommend using one of the available [OAuth libraries](https://oauth.net/code/) for your platform. - + # Try it out! - You can try out the Civic Pass API by using the following demo credentials to generate an auth token: + You can try out the Civic Pass Customer API by using the following demo credentials to generate an auth token: - `client_id: j5kwZ68j4bM8fdPAYKu7DlGQGr37eNPs`, - `client_secret: S1qSiacDUDPRVfxiSvwsRASxE0fH47U60eYeNYIt4JKSVSsgo2yy0n6V-Uz1IYBK` - - The demo credentials only work for the development networks:`solana/devnet`, `ethereum/goerli`, `ethereum/xdcApothem`, `ethereum/arbitrumGoerli`. Also, please keep in mind that since these are shared credentials, i.e. others have access to the same Civic Passes and can for example freeze them. + + The demo credentials only work for the development networks:`solana/devnet` & `ethereum/goerli`. Also, please keep in mind that since these are shared credentials, i.e. others have access to the same Civic Passes and can for example freeze them. termsOfService: https://www.civic.com/legal/terms-of-service-civic-pass-v1/ contact: @@ -78,10 +62,10 @@ paths: type: object properties: state: - $ref: '#/components/schemas/State' + $ref: "#/components/schemas/State" walletAddress: type: string - example: '4v4PL5bMZXXvQB3mvWPXLvqfJpjJmPRnPrmENnUESQQQ' + example: "4v4PL5bMZXXvQB3mvWPXLvqfJpjJmPRnPrmENnUESQQQ" issueTimestamp: type: object example: { "$gt": 1677588890 } @@ -97,7 +81,7 @@ paths: type: array items: type: object - $ref: '#/components/schemas/PassResponse' + $ref: "#/components/schemas/PassResponse" security: - pass_auth: - write:token @@ -107,11 +91,7 @@ paths: 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. - - - In the unlikely case that the issuance fails to confirm on-chain, for example with a `RETRIES_EXHAUSTED` event, clients can simply retry the request. Retrying will be protocolled in the events as expected, e.g. a new `TOKEN_ISSUED_INITIATED` and `TOKEN_ISSUED`, event will be appended. + 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 @@ -120,31 +100,32 @@ paths: required: true example: ethereum schema: - $ref: '#/components/schemas/Chain' + $ref: "#/components/schemas/Chain" - name: chainNetwork in: path description: The blockchain network required: true explode: true - example: polygonMainnet + example: matic schema: - $ref: '#/components/schemas/ChainNetwork' + $ref: "#/components/schemas/ChainNetwork" requestBody: content: application/json: schema: - $ref: '#/components/schemas/Wallet' + $ref: "#/components/schemas/Wallet" required: true responses: - '202': + "202": description: The issuance of the Civic Pass has been initiated. content: application/json: schema: - $ref: '#/components/schemas/PassResponse' - '401': + type: object + $ref: "#/components/schemas/PassResponse" + "401": description: Unauthorized - '400': + "400": description: Client error security: - pass_auth: @@ -164,7 +145,7 @@ paths: required: true example: ethereum schema: - $ref: '#/components/schemas/Chain' + $ref: "#/components/schemas/Chain" - name: wallet in: path description: The user's wallet the Civic Pass was issued to. @@ -177,17 +158,17 @@ paths: description: The blockchain network required: true explode: true - example: polygonMainnet + example: matic schema: - $ref: '#/components/schemas/ChainNetwork' + $ref: "#/components/schemas/ChainNetwork" responses: - '200': + "200": description: The Civic Pass associated with the given wallet. content: application/json: schema: - $ref: '#/components/schemas/PassResponse' - '404': + $ref: "#/components/schemas/PassResponse" + "404": description: No Civic pass is associatied with the given wallet. security: - pass_auth: @@ -197,13 +178,7 @@ paths: 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. - - - The expiration time is required to be a future date. I.e. to "immediately" expire a pass, set an expiration data a couple of minutes in the future. - - - Additionally, patching the status is **not** idempodent. I.e. trying to patch an ACTIVE Civic Pass, with the status ACTIVE, will result in an error. + 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 @@ -212,7 +187,7 @@ paths: required: true example: ethereum schema: - $ref: '#/components/schemas/Chain' + $ref: "#/components/schemas/Chain" - name: wallet in: path description: The user's wallet the Civic Pass was issued to. @@ -225,17 +200,17 @@ paths: description: The blockchain network required: true explode: true - example: polygonMainnet + example: matic schema: - $ref: '#/components/schemas/ChainNetwork' + $ref: "#/components/schemas/ChainNetwork" requestBody: content: application/json: schema: - $ref: '#/components/schemas/UpdateState' + $ref: "#/components/schemas/UpdateState" required: true responses: - '200': + "200": description: ok content: application/json: @@ -259,7 +234,7 @@ paths: required: true example: ethereum schema: - $ref: '#/components/schemas/Chain' + $ref: "#/components/schemas/Chain" - name: wallet in: path description: The user's wallet the Civic Pass was issued to. @@ -272,74 +247,84 @@ paths: description: The blockchain network required: true explode: true - example: polygonMainnet + example: matic schema: - $ref: '#/components/schemas/ChainNetwork' + $ref: "#/components/schemas/ChainNetwork" responses: - '200': + "200": description: The revocation has been initiated. security: - pass_auth: - write:token - read:token - - /account/gatekeeperNetwork: + /piirequest/{scopeRequestId}: get: tags: - - gatekeeperNetwork - summary: Retrieve a list of all your organization's custom pass types (gatekeeper networks). - description: Retrieve the list of all custom pass types (also called gatekeeper networks) managed by your organization - operationId: listGatekeeperNetworks + - 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: The list of Gatekeeper Networks associated with your organization. + 200: + description: "OK" content: application/json: schema: - type: object - properties: - records: - type: array - items: - type: object - $ref: '#/components/schemas/GatekeeperNetworkResponse' - security: - - pass_auth: - - write:token - - read:token - /account/gatekeeperNetwork/{id}: - get: + $ref: "#/components/schemas/GetPiiResponse" + /piirequest/{scopeRequestId}/status: + put: tags: - - gatekeeperNetwork - summary: Retrieve a specific pass type (gatekeeper network) by id. - description: Retrieve a specific pass type (gatekeeper network) by id. - operationId: getGatekeeperNetwork + - 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: id + - name: scopeRequestId in: path - description: The address of the gatekeeper network you want to view + 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 - required: true - example: tgnuXXNMDLK8dy7Xm1TdeGyc95MDym4bvAQCwcW21Bf + - 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: The configuration of the requested gatekeeper network - content: - application/json: - schema: - $ref: '#/components/schemas/GatekeeperNetworkResponse' - security: - - pass_auth: - - write:token - - read:token - + 200: + description: "OK" tags: - name: pass description: Issue and manage Civic Passes - - name: gatekeeperNetwork - description: View and manage settings for custom pass types + - name: piirequest + description: Get user PII and approve / reject receipt of PII components: schemas: Wallet: @@ -357,12 +342,7 @@ components: - homestead - mainnet-beta - goerli - - polygonMainnet - - polygonMumbai - - xdcMainnet - - xdcApothem - - arbitrumMainnet - - arbitrumGoerli + - matic Chain: type: string description: The chain type @@ -382,7 +362,7 @@ components: type: object properties: state: - $ref: '#/components/schemas/State' + $ref: "#/components/schemas/State" expiryTimestamp: description: The new expiration timestamp example: 1677593295 @@ -394,9 +374,9 @@ components: type: object properties: type: - $ref: '#/components/schemas/Chain' + $ref: "#/components/schemas/Chain" network: - $ref: '#/components/schemas/ChainNetwork' + $ref: "#/components/schemas/ChainNetwork" required: - type - network @@ -473,25 +453,47 @@ components: - id - onChainState - state - GatekeeperNetworkResponse: + GetPiiResponse: type: object properties: - id: - description: The address of this [Gatekeeper Network](https://docs.civic.com/civic-pass/integrate/turnkey-integration/selecting-a-pass). - type: string - example: "tgnuXXNMDLK8dy7Xm1TdeGyc95MDym4bvAQCwcW21Bf" - partner: - description: Your Civic partner id + status: + description: "The status of this PII request. The PII can be retrieved once this has reached 'verification-success'" type: string - example: "org_i9vWjKV39gluxfmU" - public: - description: Whether this gatekeeper network is viewable publicly or not - type: boolean - example: true - required: - - id - - partner - - public + 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