Skip to content
LogoLogo

Devices

Register, recover, and inspect devices holding a key share.

Recover an embedded device

POST/v2/devices/recover

Recovers an embedded device for an existing account. This endpoint retrieves the device information including the share and signer details for a previously registered account.

Header Parameters

X-Auth-Provider
string·max 64

Selects how the bearer token is validated. Omit it to use the default provider, which verifies the token against the auth service's JWKS.

Examplegoogle

Request Body

application/json
accountRequired
string

Specifies the unique account ID (starts with acc_)

Exampleacc_6f6c9067-89fa-4fc8-ac72-c242a268c584

Responses

401Error response - Unauthorized
415Unsupported Media Type - a request with a body must use Content-Type application/json.
429Too Many Requests - per-user rate limit exceeded. Retry after the interval in the Retry-After header.

Register an embedded device

POST/v2/devices/register

Registers a new device for an existing account by associating a share with the account. This is used when adding a new device to an account that already exists.

Header Parameters

X-Auth-Provider
string·max 64

Selects how the bearer token is validated. Omit it to use the default provider, which verifies the token against the auth service's JWKS.

Examplegoogle

Request Body

application/json
accountRequired
string

Specifies the unique account ID (starts with acc_)

Exampleacc_6f6c9067-89fa-4fc8-ac72-c242a268c584
shareRequired
string

The encrypted share repository data to register with the account

Example7d526b7e99fbf52850a183...

Responses

401Error response - Unauthorized
415Unsupported Media Type - a request with a body must use Content-Type application/json.
429Too Many Requests - per-user rate limit exceeded. Retry after the interval in the Retry-After header.

Create a new embedded device

POST/v2/devices/create

Creates a new account and registers the first device for it. This endpoint handles the complete setup of a new account with an embedded signer.

Header Parameters

X-Auth-Provider
string·max 64

Selects how the bearer token is validated. Omit it to use the default provider, which verifies the token against the auth service's JWKS.

Examplegoogle

Request Body

application/json
accountTypeRequired
string

Type of account to create (Smart Account or Externally Owned Account)

ExampleSmart Account
chainTypeRequired
string

Chain type (EVM or SVM)

ExampleEVM
addressRequired
string

Account blockchain address

Example0xf7b4c54cca21cccf42796502bf94e2838fbd44c4
chainId
number

Chain ID (optional)

Example80002
privateKey
string

Private key for EOA accounts (optional, for Externally Owned Accounts)

Example0x...
kmsKey
string

KMS key identifier (optional, for KMS-managed accounts)

Examplekms_...
share
string

The encrypted share repository data (optional, for embedded signers)

Example7d526b7e99fbf52850a183...

Responses

401Error response - Unauthorized
415Unsupported Media Type - a request with a body must use Content-Type application/json.
429Too Many Requests - per-user rate limit exceeded. Retry after the interval in the Retry-After header.

Initialize device registration or recovery

POST/v1/devices/init

Determines whether a user needs to register a new device or recover an existing one for a given chain. Returns REGISTER if no account exists for the user on the specified chain, or RECOVER with the primary device share if an account already exists.

Header Parameters

X-Auth-Provider
string·max 64

Selects how the bearer token is validated. Omit it to use the default provider, which verifies the token against the auth service's JWKS.

Examplegoogle

Request Body

application/json
chainIdRequired
integer <int64>

The chain ID to initialize for.

Example80002

Responses

401Error response - Unauthorized
415Unsupported Media Type - a request with a body must use Content-Type application/json.
429Too Many Requests - per-user rate limit exceeded. Retry after the interval in the Retry-After header.

Register a device (v1)

POST/v1/devices/register

Registers a new device for a user. If no account exists for the user on the given chain and address, a new account is created and the device is marked as primary. Otherwise, the device is added as a secondary device.

Header Parameters

X-Auth-Provider
string·max 64

Selects how the bearer token is validated. Omit it to use the default provider, which verifies the token against the auth service's JWKS.

Examplegoogle

Request Body

application/json
chainIdRequired
integer <int64>

The chain ID.

Example80002
addressRequired
string

Blockchain address.

Example0xf7b4c54cca21cccf42796502bf94e2838fbd44c4
shareRequired
string

The encrypted share data.

Example7d526b7e99fbf52850a183...
signerUuid
string

Signer UUID to assign (optional, generated if omitted).

Responses

401Error response - Unauthorized
415Unsupported Media Type - a request with a body must use Content-Type application/json.
429Too Many Requests - per-user rate limit exceeded. Retry after the interval in the Retry-After header.

Get a device by ID

GET/v1/devices/{deviceId}

Returns details for a specific device, including its decrypted share. Use the special value primary as the device ID to retrieve the primary device for the authenticated user.

Path Parameters

deviceIdRequired
string

The device ID, or primary to get the primary device.

Header Parameters

X-Auth-Provider
string·max 64

Selects how the bearer token is validated. Omit it to use the default provider, which verifies the token against the auth service's JWKS.

Examplegoogle

Responses

401Error response - Unauthorized
404Device not found.
429Too Many Requests - per-user rate limit exceeded. Retry after the interval in the Retry-After header.

List devices for the authenticated user

GET/v1/devices

Returns a paginated list of devices belonging to the authenticated user across all their accounts.

Query Parameters

limit
integer <int32>·min 1·max 100

Maximum number of devices to return (default 100, max 100).

Header Parameters

X-Auth-Provider
string·max 64

Selects how the bearer token is validated. Omit it to use the default provider, which verifies the token against the auth service's JWKS.

Examplegoogle

Responses

401Error response - Unauthorized
429Too Many Requests - per-user rate limit exceeded. Retry after the interval in the Retry-After header.

Create a device for an existing account

POST/v1/devices

Creates a new device and associates it with an existing account. The share is encrypted and stored.

Header Parameters

X-Auth-Provider
string·max 64

Selects how the bearer token is validated. Omit it to use the default provider, which verifies the token against the auth service's JWKS.

Examplegoogle

Request Body

application/json
accountIdRequired
string

The account ID to associate the device with.

Exampleacc_6f6c9067-89fa-4fc8-ac72-c242a268c584
addressRequired
string

Blockchain address.

Example0xf7b4c54cca21cccf42796502bf94e2838fbd44c4
chainIdRequired
integer <int64>

The chain ID.

Example80002
shareRequired
string

The encrypted share data.

Example7d526b7e99fbf52850a183...

Responses

400Account not found.
401Error response - Unauthorized
415Unsupported Media Type - a request with a body must use Content-Type application/json.
429Too Many Requests - per-user rate limit exceeded. Retry after the interval in the Retry-After header.
Presented By