REST API

These endpoints require a Portal API Key as a bearer token.

Before going live with real users, always ensure that you create clients using a Portal API Key from your Portal's Production environment. Read more here on going live with real users.

Create a new client

POST https://api.portalhq.io/api/v1/custodians/clients

Registers a new client and returns a client session token.

Headers

Name	Type	Description
Authorization*	String	Bearer <Portal API Key>
Content-Type*	String	application/json

Request Body

Name	Type	Description
isAccountAbstracted	Boolean	The client will use ERC-4337 Account Abstraction.

201: Created Success

{
  "id": "string",
  "clientApiKey": "string",
  "clientSessionToken": "string",
  "isAccountAbstracted": boolean
}

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized Request

{}

Fetches a single client

GET https://api.portalhq.io/api/v1/custodians/clients/{clientId}

Fetches the specified client for the authorized custodian.

Path Parameters

Name	Type	Description
clientId*	String	The ID of a client.

Headers

Name	Type	Description
Authorization*	String	Bearer <Portal API Key>
Content-Type*	String	application/json

200: OK Success

{
  "id": "string",
  "address": "string",
  "clientApiKey": "string",
  "isAccountAbstracted": boolean
}

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized Request

{}

Fetches a list of clients

GET https://api.portalhq.io/api/v1/custodians/clients

Fetches all clients for the authorized custodian.

Headers

Name	Type	Description
Authorization*	String	Bearer <Portal API Key>
Content-Type*	String	application/json

200: OK Success

[
  {
    "id": "string",
    "address": "string",
    "backupStatus": "string",
    "clientApiKey": "string",
    "signingStatus": "string"
  }
]

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized Request

{}

Refresh Client Session Token (CST)

POST https://api.portalhq.io/api/v1/custodians/clients/{clientId}/session

Refreshes a client's Client Session Token.

Path Parameters

Name	Type	Description
clientId	String	The ID of a client.

Headers

Name	Type	Description
Authorization*	String	Bearer <Portal API Key>
Content-Type*	String	application/json

200: OK Success

{
  "id": "string",
  "clientSessionToken": "string",
  "isAccountAbstracted": boolean
}

400: Bad Request Bad Request

{
  "error": "string"
}

401: Unauthorized Unauthorized Request

{
  "error": "string"
}

Generate Client Web One-Time Password (OTP)

POST https://api.portalhq.io/api/v1/custodians/clients/{clientId}/web-otp

Generate a one-time password for a client.

Path Parameters

Name	Type	Description
clientId*	String	The ID of a client.

Headers

Name	Type	Description
Authorization*	String	Bearer <Portal API Key>
Content-Type*	String	application/json

200: OK Success

{
  "id": "string"
  "otp": "string"
}

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized

{}

Notify Portal when you (fail to) store the encrypted client backup share.

PUT https://api.portalhq.io/api/v1/clients/me/wallet/stored-client-backup-share

By letting Portal know that you stored the encrypted client backup share successfully, the client is now capable of running portal.recover.

Headers

Name	Type	Description
Authorization*	String	Bearer <Client API Key>
Content-Type*	String	application/json

Request Body

Name	Type	Description
backupMethod*	"ICLOUD" | "GDRIVE" | "PASSKEY" | "PASSWORD"	Provide the backup method used when portal.backup was ran.
success*	Boolean	Provide false if you failed to store the client backup share.

204: No Content Success

No response body.

400: Bad Request Bad Request

{}

401: Unauthorized Unauthorized Request

{}

Retrieve the client's signing shares' metadata.

GET https://api.portalhq.io/api/v1/clients/me/signing-share-pairs

Verify that a client has the correct signing shares' metadata.

Headers

Name	Type	Description
Authorization*	String	Bearer <Client API Key>
Content-Type*	String	application/json

200: OK Success

[
  {
    "id": "string",
    "createdAt": "2023-11-28T21:55:13.630Z"
    "status": "completed"
  },
  {
    "id": "string",
    "createdAt": "2023-11-28T21:55:13.630Z"
    "status": "incomplete"
  }
]

401: Unauthorized Unauthorized Request

Retrieve the client's backup shares' metadata.

GET https://api.portalhq.io/api/v1/clients/me/backup-share-pairs

Verify that a client has the correct backup shares' metadata.

Headers

Name	Type	Description
Authorization*	String	Bearer <Client API Key>
Content-Type*	String	application/json

200: OK Success

[
  {
    "backupMethod": "UNKNOWN", // Legacy (MPC Version 1-5)
    "id": "string",
    "createdAt": "2023-11-28T21:55:13.630Z",
    "status": "completed"
  },
  {
    "backupMethod": "GDRIVE",
    "id": "string",
    "createdAt": "2023-11-28T21:55:13.630Z",
    "status": "incomplete"
  },
  {
    "backupMethod": "ICLOUD",
    "id": "string",
    "createdAt": "2023-11-28T21:55:13.630Z",
    "status": "incomplete"
  },
  {
    "backupMethod": "PASSWORD",
    "id": "string",
    "createdAt": "2023-11-28T21:55:13.630Z",
    "status": "completed"
  },
  {
    "backupMethod": "PASSKEY",
    "id": "string",
    "createdAt": "2023-11-28T21:55:13.630Z",
    "status": "completed"
  },
]

401: Unauthorized Unauthorized Request