Collection of endpoints related to Identity
openapi: 3.0.0
info:
title: Privado ID - Issuer Agent Identity API
description: "The Issuer Node Core API is ideal for users who need multiple identities and for integrator profiles, who want to \ncreate solutions based on Privado ID functionalities and might be interested in having access to low level \ninformation such as Merkle Trees.\nThe Issuer Node API provide the following functionalities:\n* Create and retrieve Identities\n* Create a Verifiable Credential (VC)\n* Retrieve a Verifiable Credential or a list of Verifiable Credentials\n* Generate JSON to create a QR Code and use that to accept credentials in a wallet\n* Revoke a Verifiable Credential\n* Check revocation status of a Verifiable Credential\n* Retrieve the Revocation Status of a Verifiable Credential\n* Call Agent Endpoint using the Wallet App\n* Handle connections.\n"
version: '1'
tags:
- name: Identity
description: Collection of endpoints related to Identity
paths:
/v2/identities:
post:
summary: Create Identity
operationId: CreateIdentity
description: "Endpoint to create an identity to issue credentials.\nIssuer node supports two types of keys (field `type`):\n* BJJ Keys\n* ETH Keys\n\n`credentialStatusType` field is optional and and defines how the auth core claim will be evaluated during \nthe process to verify that it has not been revoked.\n"
tags:
- Identity
security:
- basicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateIdentityRequest'
responses:
'201':
description: Identity created
content:
application/json:
schema:
$ref: '#/components/schemas/CreateIdentityResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'409':
$ref: '#/components/responses/409'
'500':
$ref: '#/components/responses/500'
get:
summary: Get Identities
operationId: GetIdentities
description: Endpoint to get all the identities
tags:
- Identity
security:
- basicAuth: []
responses:
'200':
description: all good
content:
application/json:
schema:
type: array
x-omitempty: false
items:
$ref: '#/components/schemas/GetIdentitiesResponse'
'401':
$ref: '#/components/responses/401'
'500':
$ref: '#/components/responses/500'
/v2/identities/{identifier}:
patch:
summary: Update Identity
operationId: UpdateIdentity
description: 'Endpoint to update the identity.
The displayName field is used to identify the identity in the UI.
'
tags:
- Identity
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/pathIdentifier'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- displayName
properties:
displayName:
type: string
example: KYCAgeCredential Issuer identity
responses:
'200':
description: Identity updated
content:
application/json:
schema:
$ref: '#/components/schemas/GenericMessage'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'500':
$ref: '#/components/responses/500-CreateIdentity'
get:
summary: Get Identity Detail
operationId: GetIdentityDetails
description: Endpoint to get an identity details
tags:
- Identity
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/pathIdentifier'
responses:
'200':
description: Identity top up successfully
content:
application/json:
schema:
$ref: '#/components/schemas/GetIdentityDetailsResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'500':
$ref: '#/components/responses/500'
/v2/identities/{identifier}/state/retry:
post:
summary: Retry Publish Identity State
operationId: RetryPublishState
description: Endpoint to retry publish identity state. If the publish state failed, this endpoint can be used to retry the publish.
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/pathIdentifier'
tags:
- Identity
responses:
'202':
description: Publish state successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PublishIdentityStateResponse'
'400':
$ref: '#/components/responses/400'
'500':
$ref: '#/components/responses/500'
/v2/identities/{identifier}/state/publish:
post:
summary: Publish Identity State
operationId: PublishIdentityState
description: Endpoint to publish identity state.
tags:
- Identity
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/pathIdentifier'
responses:
'200':
description: No transactions to process to the given identity
content:
application/json:
schema:
$ref: '#/components/schemas/GenericMessage'
'202':
description: Transaction ID of the published state
content:
application/json:
schema:
$ref: '#/components/schemas/PublishIdentityStateResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'500':
$ref: '#/components/responses/500'
/v2/identities/{identifier}/state/transactions:
get:
summary: Get Identity State Transactions
operationId: GetStateTransactions
description: 'Endpoint to get identity state transactions.
To get all transactions, use the filter `all`. To get the latest transaction, use the filter `latest`.
The transactions are paginated for `filter=all`. If the filter is not provided, the default is `all`.
'
security:
- basicAuth: []
tags:
- Identity
parameters:
- $ref: '#/components/parameters/pathIdentifier'
- in: query
name: filter
schema:
type: string
enum:
- all
- latest
default: all
- in: query
name: page
schema:
type: integer
format: uint
minimum: 1
example: 5
description: Page to fetch. First is 1. If not provided, default is 1.
- in: query
name: max_results
schema:
type: integer
format: uint
example: 10
default: 50
description: Number of items to fetch on each page. Default is 10.
- in: query
name: sort
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- publishDate
- -publishDate
- status
- -status
default: -publishDate
description: 'The minus sign (-) before createdAt means descending order.
'
responses:
'200':
description: State transactions
content:
application/json:
schema:
$ref: '#/components/schemas/StateTransactionsPaginated'
'400':
$ref: '#/components/responses/400'
'500':
$ref: '#/components/responses/500'
/v2/identities/{identifier}/state/status:
get:
summary: Get Identity State Status
operationId: GetStateStatus
description: 'Endpoint to get identity state status, if the identity status is published or not.
If the status is `pendingActions` is true it means that the identity has pending actions to be published.
'
security:
- basicAuth: []
tags:
- Identity
parameters:
- $ref: '#/components/parameters/pathIdentifier'
responses:
'200':
description: State status
content:
application/json:
schema:
$ref: '#/components/schemas/StateStatusResponse'
'400':
$ref: '#/components/responses/400'
'500':
$ref: '#/components/responses/500'
/v2/identities/{identifier}/create-auth-credential:
post:
summary: Create Auth Credential
operationId: CreateAuthCredential
description: 'Endpoint to create a new Auth Credential
* keyID - only babyjubjub keys supported
'
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/pathIdentifier2'
tags:
- Identity
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAuthCredentialRequest'
responses:
'201':
description: Key added successfully
content:
application/json:
schema:
type: object
required:
- id
- credentialStatusType
properties:
id:
type: string
description: The ID of the created Auth Credential
x-go-type: uuid.UUID
x-go-type-import:
name: uuid
path: github.com/google/uuid
example: 8edd8112-c415-11ed-b036-debe37e1cbd6
'400':
$ref: '#/components/responses/400'
'500':
$ref: '#/components/responses/500'
/v2/identities/{identifier}/keys/{id}:
delete:
summary: Delete Key
operationId: DeleteKey
description: Remove a specific key for the provided identity.
tags:
- Identity
security:
- basicAuth: []
parameters:
- $ref: '#/components/parameters/pathIdentifier2'
- $ref: '#/components/parameters/pathKeyID'
responses:
'200':
description: Key deleted
content:
application/json:
schema:
$ref: '#/components/schemas/GenericMessage'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'401':
$ref: '#/components/responses/401'
'500':
$ref: '#/components/responses/500'
components:
responses:
500-CreateIdentity:
description: Internal Server error
content:
application/json:
schema:
type: object
properties:
requestID:
type: string
code:
type: integer
error:
type: string
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/GenericErrorMessage'
'500':
description: Internal Server error
content:
application/json:
schema:
$ref: '#/components/schemas/GenericErrorMessage'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/GenericErrorMessage'
'403':
description: Permission Denied
content:
application/json:
schema:
$ref: '#/components/schemas/GenericErrorMessage'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/GenericErrorMessage'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/GenericErrorMessage'
schemas:
PublishIdentityStateResponse:
type: object
properties:
txID:
type: string
claimsTreeRoot:
type: string
state:
type: string
revocationTreeRoot:
type: string
rootOfRoots:
type: string
CreateIdentityRequest:
type: object
required:
- didMetadata
properties:
didMetadata:
type: object
required:
- method
- blockchain
- network
- type
properties:
method:
type: string
x-omitempty: false
example: polygonid
blockchain:
type: string
x-omitempty: false
example: polygon
network:
type: string
x-omitempty: false
example: amoy
type:
type: string
x-omitempty: false
example: BJJ
enum:
- BJJ
- ETH
credentialStatusType:
type: string
x-omitempty: true
example: Iden3ReverseSparseMerkleTreeProof
enum:
- Iden3commRevocationStatusV1.0
- Iden3ReverseSparseMerkleTreeProof
- Iden3OnchainSparseMerkleTreeProof2023
displayName:
type: string
x-omitempty: false
example: KYCAgeCredential Issuer identity
GenericMessage:
type: object
required:
- message
properties:
message:
type: string
StateTransactions:
type: array
items:
$ref: '#/components/schemas/StateTransaction'
StateStatusResponse:
type: object
required:
- pendingActions
properties:
pendingActions:
type: boolean
example: true
IdentityState:
type: object
required:
- stateID
- identifier
- status
- modifiedAt
- createdAt
properties:
stateID:
type: integer
format: int64
x-go-json-ignore: true
identifier:
type: string
x-go-json-ignore: true
state:
type: string
rootOfRoots:
type: string
claimsTreeRoot:
type: string
revocationTreeRoot:
type: string
blockTimestamp:
type: integer
blockNumber:
type: integer
txID:
type: string
previousState:
type: string
status:
type: string
modifiedAt:
$ref: '#/components/schemas/TimeUTC'
createdAt:
$ref: '#/components/schemas/TimeUTC'
CreateIdentityResponse:
type: object
required:
- identity
- status
- keyType
- credentialStatusType
properties:
identifier:
type: string
displayName:
type: string
state:
$ref: '#/components/schemas/IdentityState'
address:
type: string
x-omitempty: true
balance:
type: string
x-omitempty: true
keyType:
type: string
credentialStatusType:
type: string
example: Iden3ReverseSparseMerkleTreeProof
enum:
- Iden3commRevocationStatusV1.0
- Iden3ReverseSparseMerkleTreeProof
- Iden3OnchainSparseMerkleTreeProof2023
GetIdentityDetailsResponse:
type: object
required:
- identifier
- state
- status
- keyType
- credentialStatusType
- authCredentialsIDs
properties:
identifier:
type: string
displayName:
x-omitempty: false
type: string
state:
$ref: '#/components/schemas/IdentityState'
address:
type: string
x-omitempty: true
balance:
type: string
x-omitempty: true
keyType:
type: string
credentialStatusType:
type: string
example: Iden3ReverseSparseMerkleTreeProof
enum:
- Iden3commRevocationStatusV1.0
- Iden3ReverseSparseMerkleTreeProof
- Iden3OnchainSparseMerkleTreeProof2023
authCredentialsIDs:
type: array
items:
type: string
GenericErrorMessage:
type: object
required:
- message
properties:
message:
type: string
example: Something happen
PaginatedMetadata:
type: object
required:
- total
- page
- max_results
properties:
total:
type: integer
format: uint
example: 1
page:
type: integer
format: uint
example: 1
max_results:
type: integer
format: uint
example: 50
CreateAuthCredentialRequest:
type: object
required:
- keyID
- credentialStatusType
properties:
keyID:
type: string
x-omitempty: false
example: ZGlkOnBvbHlnb25pZDpwb2x5Z29uOmFtb3k6MnFRNjhKa1JjZjN5cXBYanRqVVQ3WjdVeW1TV0hzYll
expiration:
type: integer
format: int64
version:
type: integer
format: uint32
revNonce:
type: integer
format: uint64
credentialStatusType:
type: string
x-omitempty: true
example: Iden3ReverseSparseMerkleTreeProof
enum:
- Iden3commRevocationStatusV1.0
- Iden3ReverseSparseMerkleTreeProof
- Iden3OnchainSparseMerkleTreeProof2023
GetIdentitiesResponse:
type: object
required:
- identifier
- method
- blockchain
- network
properties:
identifier:
type: string
x-omitempty: false
example: did:polygonid:polygon:amoy:2qMZrfBsXuGFTwSqkqYki78zF3pe1vtXoqH4yRLsfs
credentialStatusType:
type: string
x-omitempty: true
example: Iden3ReverseSparseMerkleTreeProof
enum:
- Iden3commRevocationStatusV1.0
- Iden3ReverseSparseMerkleTreeProof
- Iden3OnchainSparseMerkleTreeProof2023
method:
type: string
x-omitempty: false
example: polygonid
blockchain:
type: string
x-omitempty: false
example: polygon
network:
type: string
x-omitempty: false
example: amoy
displayName:
type: string
x-omitempty: false
example: KYCAgeCredential Issuer identity
StateTransaction:
type: object
required:
- id
- txID
- state
- publishDate
- status
properties:
id:
type: integer
format: int64
example: 1
txID:
type: string
example: 0x8f271174b45ba7892d83...
state:
type: string
example: 13f9aadd4801d775e85a7ef45c2f6d02cdf83f0d724250417b165ff9cd88ee21
publishDate:
$ref: '#/components/schemas/TimeUTC'
status:
type: string
enum:
- created
- pending
- published
- failed
example: published
StateTransactionsPaginated:
type: object
required:
- items
- meta
properties:
items:
$ref: '#/components/schemas/StateTransactions'
meta:
$ref: '#/components/schemas/PaginatedMetadata'
TimeUTC:
type: string
x-go-type: timeapi.Time
x-go-type-import:
name: timeapi
path: github.com/polygonid/sh-id-platform/internal/timeapi
example: '2023-10-26T10:59:08Z'
x-omitempty: false
parameters:
pathIdentifier:
name: identifier
in: path
required: true
description: Issuer identifier
schema:
type: string
pathIdentifier2:
name: identifier
in: path
required: true
description: Issuer identifier
schema:
type: string
x-go-type: Identity
x-go-type-import:
name: customIdentity
path: github.com/polygonid/sh-id-platform/internal/api
pathKeyID:
name: id
in: path
required: true
description: Key ID in base64
schema:
type: string
securitySchemes:
basicAuth:
type: http
scheme: basic