Accesses Management
An Access is a login bound to your Business Account. Each access has its own credentials (email + password), MFA, and a granular set of permissions that gate which Avenia API operations it can call. Accesses can be issued to teammates, services, or signers without sharing the original admin credentials.
This guide is the complete reference for the /v2/auth/accesses API. For a higher-level overview of how an access relates to your account and subaccounts, see About Login → Access.
You must have TOTP MFA enabled on the calling access to create, update, or delete accesses, and to manage the subaccount blacklist. Click here to learn how to set this up.
Only the admin access, and accesses granted manageAccesses, can manage other accesses. The first access of your Business Account is the admin. The /v2/auth/accesses endpoints accept the bearer token of a login only — API-key authentication is not accepted on them.
Permissions Reference
Permissions are passed as a permissions object in POST and PATCH requests. They are returned inside accessPermission on GET responses.
| Field | Type | Default on create | Description |
|---|---|---|---|
admin | boolean | false | Read-only on responses. Only the first access of the Business Account is admin. Admin passes every permission check below, and is always returned with manageAccesses: true. |
viewOnly | boolean | false | Read-only access. When true, the access can list balances and transactions but cannot move funds or change anything. |
payOut | boolean | false | Allows pay-out operations (e.g. stable → fiat, off-ramp) and on-chain transfers to external wallets. Without it, a ticket can only output to INTERNAL. |
convert | boolean | true ¹ | Required to exchange currencies: a ticket whose input and output are different money, an end-of-day (EoD) trade, or a payment session that can be paid in a different money than it credits. See Currency Exchanges. Without it the request returns 403. |
payIn | boolean | true ¹ | Pay-in flag. Stored on the access and returned on GET. |
onChain | boolean | true ¹ | On-chain flag. Stored on the access and returned on GET. On-chain transfers to external wallets are governed by payOut. |
manageAssets | boolean | true | Required to create an INTERNAL ticket that credits another account of the Business Account (transfers between the main account and its subaccounts). Conversions within one account do not need it. Without it the ticket returns 403. |
markup | boolean | true | Allows the access to set/override quote markup. |
beneficiary | boolean | true | Allows the access to manage beneficiaries (bank accounts, wallets). |
enforceAllowedBeneficiaries | boolean | false | When true, the access can only operate on a curated allow-list of beneficiaries. |
createSubAccounts | boolean | true | Allows the access to create subaccounts. false refuses subaccount creation with 403. |
manageAccesses | boolean | false | Lets a non-admin access list, create and edit other accesses. Only the admin can grant or revoke it. See Delegated Access Management. |
operationRequester | boolean | false | Puts the access under multi-signature approval. See Multi-Signature Approval. |
operationApprover | boolean | false | Allows the access to approve or reject the pending operations of requester accesses. |
¹ false when viewOnly is true.
Currency Exchanges
For convert, a fiat currency and its tokens count as the same money: BRL/BRLA, USD/USDC/USDCe/USDT/USDM, EUR/EURC, ARS/ARSA and COP/COPA. Every other currency is its own. A ticket between two currencies of the same group is a pay-in or a pay-out, not an exchange.
| Operation | Needs convert |
|---|---|
| BRL (PIX) → BRLA, BRLA → BRL (PIX) | No |
| USD (WIRE) → USDC | No |
| USDC ↔ USDT | No |
| BRL (PIX) → USDC, BRLA → USDT | Yes |
| EoD trade (BRLA ↔ USDC) | Yes |
| Payment session paid in BRL, crediting USDC | Yes |
The same applies to payment sessions (POST /v2/account/payment-session): if any of the paymentOptions currencies is a different money from the outputCurrency, creating the session requires convert.
Without convert, an exchange is refused with 403 Convert permission is required to exchange currencies. For an access under multi-signature approval the refusal comes when the operation is requested, before it goes to the approvers.
Outbound movement of funds (pay-outs and on-chain transfers to external wallets) is governed by payOut, a change of currency by convert, and transfers between your own accounts by manageAssets. The admin access passes all three checks.
Additional Fields
These fields are accepted alongside permissions in the request body:
| Field | Type | Description |
|---|---|---|
blacklistedSubAccountIds | array of string | UUIDs of accounts this access is not allowed to operate on. See Subaccount Blacklist. |
allowedSubAccountsOnly | boolean | true limits the access to the subaccounts in allowedSubAccountIds, so a subaccount created later stays hidden from it. See Allowed Subaccounts. |
allowedSubAccountIds | array of string | POST only, with allowedSubAccountsOnly: true: UUIDs of the subaccounts the access may operate on. At most 100. |
addAllowedSubAccountIds | array of string | PATCH only, with allowedSubAccountsOnly: true: UUIDs of the subaccounts added to the allowed ones. At most 1000 per request. |
removeAllowedSubAccountIds | array of string | PATCH only, with allowedSubAccountsOnly: true: UUIDs of the subaccounts taken off the allowed ones. At most 1000 per request. |
approverAccessIds | array of string | Only for operationRequester accesses: UUIDs of the accesses that can approve its operations. |
minApprovals | integer | Only for operationRequester accesses: approvals needed before an operation runs. Required when approverAccessIds is sent; must be greater than 0 and no greater than the number of approvers. |
multisigNotifications | boolean | PATCH only. Turns the multi-signature notification emails of the access on or off. Omitted keeps the stored value. |
Multi-Signature Approval
When operationRequester is true, operations of that access that move funds or register beneficiaries (tickets, beneficiary bank accounts and wallets, wallet qualification, fee account deposits and withdrawals) are not executed right away: the request returns 202 Accepted with an operationId, and the approval that brings its approverAccessIds to minApprovals executes the operation on behalf of the requester. Approvers must be accesses with operationApprover (or the admin). List Approver Accesses returns the candidates. See Multi-Signature Operations for the approval endpoints.
Delegated Access Management
An access with manageAccesses (a delegate) has the same MFA and OTP requirements as the admin. It can call:
| Endpoint | Delegate | Admin |
|---|---|---|
GET /accesses, GET /accesses/{access-id} | ✅ | ✅ |
GET /accesses/approvers | ✅ | ✅ |
GET /accesses/restricted | ✅ | ✅ |
GET /accesses/{access-id}/blacklist | ✅ | ✅ |
POST /accesses (invite), PATCH /accesses | ✅ | ✅ |
DELETE /accesses/{access-id} | — | ✅ |
POST / DELETE /accesses/{access-id}/blacklist | — | ✅ |
Any other access gets 403 requires admin or manageAccesses access on the delegate endpoints, and 403 requires admin access on the admin-only ones. GET /accesses/restricted is also open to an access with createSubAccounts.
To keep a delegate from widening its own reach, its invites and edits are checked against what the target access will store — on POST after the defaults are applied, on PATCH after the omitted fields are resolved. A permission the delegate lacks must therefore be sent explicitly as false when its default, or the stored value, is true. Each rule is refused with 403:
| Rule | Applies to | Message |
|---|---|---|
Only the admin grants manageAccesses. Sending manageAccesses: false is accepted. | POST, PATCH | only the admin can grant the manageAccesses permission |
The target cannot get payIn, payOut, convert, onChain, markup, beneficiary, manageAssets, createSubAccounts or operationApprover unless the delegate has it. | POST, PATCH | you cannot grant the <permission> permission, which you do not have |
If the delegate is viewOnly, has enforceAllowedBeneficiaries or is an operationRequester, the target must keep that flag too. | POST, PATCH | the access must keep <permission>, which applies to you |
| Every account blacklisted for the delegate, the main account included, must be blacklisted for the target too. | POST, PATCH | the access must not see account <id>, which is hidden from you |
If the delegate has allowedSubAccountsOnly, the target must have it too, and be allowed only subaccounts allowed to the delegate. | POST, PATCH | the access must see only sub-accounts allowed to it, as you do / the access must not see sub-account <id>, which is not allowed to you |
The delegate cannot be one of the approverAccessIds of an access it invites. | POST | you cannot approve the operations of an access you invite |
A delegate that is an operationRequester can only invite requesters (operationRequester: true) with its own approverAccessIds and minApprovals. When both are omitted, the server copies the delegate's. | POST | the access must need the same approvals as you: your approvers and minimum approvals |
A delegate cannot edit the admin access, its own access, or another access with manageAccesses. | PATCH | you cannot edit the admin access / you cannot edit your own access / you cannot edit an access that manages accesses |
A delegate cannot edit an access that already has more than the delegate: a permission from the list above that the delegate lacks, no viewOnly / enforceAllowedBeneficiaries / operationRequester the delegate is under, or sight of an account blacklisted for, or a subaccount not allowed to, the delegate. | PATCH | you cannot edit an access with permissions you do not have |
A delegate cannot change multi-signature settings. operationRequester and operationApprover must be sent with their stored value (omitted means false); approverAccessIds and minApprovals must be omitted or sent unchanged. | PATCH | only the admin can change multi-signature settings |
An invite sent by a delegate is checked again when it is accepted — see Validate Access.
Limits
- Maximum of 100 accesses per Business Account (admin included). Further
POST /accesses/calls return HTTP 400. - An invite can allow at most 100 subaccounts through
allowedSubAccountIds. An update adds and removes at most 1000 each; the allowed subaccounts of an access have no limit. - Email is normalized to lowercase server-side.
- The access creation token sent by email is valid for 10 minutes.
Create Access (Step 1 — Invite)
Sends an email to the new access with a token to set their password. The calling access must be admin (or hold manageAccesses) with MFA enabled.
Endpoint
Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
otp | string | Yes | TOTP code from the caller's authenticator app. |
email | string | Yes | Email of the new access. Must be a valid address, ≤ 256 characters. |
permissions | object | Yes | Permission flags. See Permissions Reference. |
permissions.payOut | boolean | No | Defaults to false. |
permissions.viewOnly | boolean | No | Defaults to false. |
permissions.convert | boolean | No | Defaults to true (false if viewOnly). |
permissions.payIn | boolean | No | Defaults to true (false if viewOnly). |
permissions.onChain | boolean | No | Defaults to true (false if viewOnly). |
permissions.manageAssets | boolean | No | Defaults to true. |
permissions.markup | boolean | No | Defaults to true. |
permissions.beneficiary | boolean | No | Defaults to true. |
permissions.enforceAllowedBeneficiaries | boolean | No | Defaults to false. |
permissions.createSubAccounts | boolean | No | Defaults to true. |
permissions.manageAccesses | boolean | No | Defaults to false. Only the admin access can set it to true. |
permissions.operationRequester | boolean | No | Defaults to false. |
permissions.operationApprover | boolean | No | Defaults to false. |
blacklistedSubAccountIds | array of string | No | Account UUIDs this access cannot operate on. |
allowedSubAccountsOnly | boolean | No | Defaults to false. See Allowed Subaccounts. |
allowedSubAccountIds | array of string | No | Subaccount UUIDs the access may operate on. Only with allowedSubAccountsOnly: true. |
approverAccessIds | array of string | No | Approvers of a requester access. Requires minApprovals. |
minApprovals | integer | No | Approvals needed for a requester access. |
Request body
{
"otp": "999999",
"email": "your.new.access.email@provider.com",
"permissions": {
"payOut": true,
"viewOnly": false,
"convert": true,
"payIn": true,
"onChain": true,
"manageAssets": false,
"markup": true,
"beneficiary": true,
"enforceAllowedBeneficiaries": false,
"createSubAccounts": false,
"manageAccesses": false
},
"blacklistedSubAccountIds": [],
"allowedSubAccountsOnly": false
}
Request example
curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/accesses/" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-d '{
"otp": "999999",
"email": "your.new.access.email@provider.com",
"permissions": {
"payOut": true,
"viewOnly": false
}
}'
A 200 OK is returned and an email with a creation token is sent to the new access. The token is valid for 10 minutes. The access is only created, with the permissions sent here, once the recipient completes Step 2.
Validate Access (Step 2 — Set Password)
The recipient of the invitation email completes the access creation by setting a password. No bearer token is required for this call — only the email token returned in the invitation URL.
Endpoint
URL Parameters
| Field | Type | Description |
|---|---|---|
token | string | Email token from the invitation link (10-min TTL). |
Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
password | string | Yes | New password for the access (1–64 characters). |
confirmPassword | string | Yes | Must match password. |
Request body
{
"password": "UseAStrongPassword123!",
"confirmPassword": "UseAStrongPassword123!"
}
Request example
curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/accesses/validate/eyJhdXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-d '{
"password": "UseAStrongPassword123!",
"confirmPassword": "UseAStrongPassword123!"
}'
A 201 Created confirms the password was set and the access is ready to log in.
If the invite was sent by a manageAccesses delegate, it is checked against that delegate again at this point, and refused with 403 when:
| Condition | Message |
|---|---|
| The delegate's access was deleted. | the access that sent this invite no longer exists |
The delegate no longer has manageAccesses. | the access that sent this invite can no longer manage accesses |
| The delegate could no longer send this invite (its permissions, blacklist, allowed subaccounts or approvals changed). | this invite grants more than the access that sent it can grant now |
A new invite has to be sent. Invites sent by the admin are not re-checked.
List Accesses
Returns the accesses linked to the calling Business Account, newest first (up to 100). Optional query parameters filter by email, by individual permission flags or by a subaccount the accesses see. allowedSubAccountsOnly tells which accesses see only their allowed subaccounts.
Endpoint
Query Parameters
| Field | Type | Description |
|---|---|---|
email | string | Filter by email (exact match; emails are stored in lowercase). |
payOut | boolean | Filter by payOut permission. |
viewOnly | boolean | Filter by viewOnly permission. |
convert | boolean | Filter by convert permission. |
payIn | boolean | Filter by payIn permission. |
onChain | boolean | Filter by onChain permission. |
createdAfter | int64 | Unix epoch timestamp in milliseconds (UTC) — e.g. 1700000000000. Returns accesses created on or after this instant (createdAt >= createdAfter). |
createdBefore | int64 | Unix epoch timestamp in milliseconds (UTC) — e.g. 1800000000000. Returns accesses created on or before this instant (createdAt <= createdBefore). |
seesSubAccountId | string (UUID) | Returns only the accesses that see this subaccount: it is not blacklisted for them and, for an access limited to allowed subaccounts, it is one of them. It must be a subaccount you see too; otherwise the request is refused with seesSubAccountId is invalid. |
createdAfter / createdBefore are Unix epoch timestamps in milliseconds, UTC (13 digits for current dates, e.g. 1700000000000) — not seconds (10 digits). If you have a value in seconds, multiply it by 1000. Both bounds are inclusive here (createdAt >= createdAfter and createdAt <= createdBefore), and the returned createdAt is an RFC3339 UTC string ending in Z. Convert local date boundaries to UTC before computing the epoch.
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/auth/accesses?email=your.new.access.email@provider.com&payOut=true" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Response
{
"accesses": [
{
"id": "00000000-0000-0000-0000-000000000000",
"email": "your.new.access.email@provider.com",
"createdAt": "2025-02-07T19:54:17.727744Z",
"updatedAt": "2025-02-07T19:54:17.727744Z",
"frozenUntil": "0001-01-01T00:00:00Z",
"accessPermission": {
"id": "11111111-1111-1111-1111-111111111111",
"admin": false,
"payIn": true,
"payOut": true,
"convert": true,
"onChain": true,
"viewOnly": false,
"markup": true,
"beneficiary": true,
"enforceAllowedBeneficiaries": false,
"operationRequester": false,
"operationApprover": false,
"createSubAccounts": true,
"manageAssets": true,
"manageAccesses": false,
"updatedAt": "2025-02-07T19:54:17.727744Z"
},
"multisigNotifications": true,
"allowedSubAccountsOnly": false,
"mfa": {
"id": "22222222-2222-2222-2222-222222222222",
"createdAt": "2025-02-18T00:36:47.329722Z",
"updatedAt": "2025-02-18T00:36:47.329722Z"
}
}
]
}
Get Access by ID
Endpoint
URL Parameters
| Field | Type | Required | Description |
|---|---|---|---|
access-id | string | Yes | UUID of an existing access. |
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/auth/accesses/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Response
{
"access": {
"id": "00000000-0000-0000-0000-000000000000",
"email": "your.new.access.email@provider.com",
"createdAt": "2025-02-07T19:54:17.727744Z",
"updatedAt": "2025-02-07T19:54:17.727744Z",
"frozenUntil": "0001-01-01T00:00:00Z",
"accessPermission": {
"id": "11111111-1111-1111-1111-111111111111",
"admin": false,
"payIn": true,
"payOut": true,
"convert": true,
"onChain": true,
"viewOnly": false,
"markup": true,
"beneficiary": true,
"enforceAllowedBeneficiaries": false,
"operationRequester": true,
"operationApprover": false,
"createSubAccounts": true,
"manageAssets": true,
"manageAccesses": false,
"updatedAt": "2025-02-07T19:54:17.727744Z"
},
"multisigConfig": {
"approverAccessIds": ["33333333-3333-3333-3333-333333333333"],
"minApprovals": 1
},
"multisigNotifications": true
}
}
multisigConfig is only returned for an access with operationRequester.
Update Access Permissions
Updates the permissions, blacklist and multi-signature settings of an existing access. Caller must be admin (or hold manageAccesses) with MFA enabled.
Endpoint
Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | UUID of the access to update. |
otp | string | Yes | TOTP code from the caller's authenticator app. |
permissions | object | Yes | Same fields as in Create. See below for what an omitted field does. |
blacklistedSubAccountIds | array of string | No | Replaces the access blacklist; [] clears it. Use the dedicated Blacklist endpoints for incremental updates. |
allowedSubAccountsOnly | boolean | No | true keeps the access to its allowed subaccounts, changed by the two fields below; false drops them and the access sees every subaccount again but the blacklisted ones. |
addAllowedSubAccountIds | array of string | No | Only with allowedSubAccountsOnly: true: subaccounts to allow. One already allowed is left as it is. |
removeAllowedSubAccountIds | array of string | No | Only with allowedSubAccountsOnly: true: subaccounts to take off. A subaccount cannot be in both lists. |
approverAccessIds | array of string | No | Replaces the approvers of a requester access. |
minApprovals | integer | No | Approvals needed for a requester access. |
multisigNotifications | boolean | No | Turns the multi-signature notification emails of the access on or off. |
A PATCH does not apply the create defaults. What an omitted field does depends on the field:
- Keeps the stored value:
convert,payIn,onChain,manageAssets,manageAccesses,createSubAccounts, and the top-levelblacklistedSubAccountIds,allowedSubAccountsOnly(with the allowed subaccounts),approverAccessIds,minApprovalsandmultisigNotifications. - Is set to
false:payOut,viewOnly,markup,beneficiary,enforceAllowedBeneficiaries,operationRequesterandoperationApprover.
Always send the second group with the value you want the access to keep — read it first with Get Access by ID. Setting operationRequester to false also removes the access's approvers and minApprovals.
Request body
{
"id": "00000000-0000-0000-0000-000000000000",
"otp": "999999",
"permissions": {
"payOut": true,
"viewOnly": false,
"convert": false,
"manageAssets": false,
"markup": false,
"beneficiary": true,
"enforceAllowedBeneficiaries": true,
"operationRequester": false,
"operationApprover": false
},
"blacklistedSubAccountIds": []
}
Request example
curl -X PATCH "https://api.sandbox.avenia.io:10952/v2/auth/accesses/" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-d '{
"id": "00000000-0000-0000-0000-000000000000",
"otp": "999999",
"permissions": {
"payOut": true,
"viewOnly": false,
"markup": true,
"beneficiary": true,
"enforceAllowedBeneficiaries": false,
"operationRequester": false,
"operationApprover": false
}
}'
A 200 OK confirms the update.
Delete Access
Deletes an existing access and invalidates its JWT and refresh tokens. Caller must be admin with MFA enabled; a manageAccesses delegate gets 403. The admin access itself cannot be deleted.
Endpoint
URL Parameters
| Field | Type | Required | Description |
|---|---|---|---|
access-id | string | Yes | UUID of the access to delete. |
Query Parameters
| Field | Type | Required | Description |
|---|---|---|---|
otp | string | Yes | TOTP code from the authenticator app. |
Request example
curl -X DELETE "https://api.sandbox.avenia.io:10952/v2/auth/accesses/00000000-0000-0000-0000-000000000000?otp=999999" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
List Approver Accesses
Returns the accesses that can approve multi-signature operations (those with operationApprover, and the admin) — the candidates for approverAccessIds.
Endpoint
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/auth/accesses/approvers" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
List Restricted Accesses
Returns, sorted by email, the other accesses limited to their allowed subaccounts: the candidates for allowedAccessIds when creating a subaccount. Only id and email are returned. Besides the admin and manageAccesses delegates, an access with createSubAccounts can call it. Any other access gets 403 requires admin, manageAccesses or createSubAccounts access.
Endpoint
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/auth/accesses/restricted" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Response
{
"accesses": [
{
"id": "22222222-2222-2222-2222-222222222222",
"email": "advisor@example.com"
}
]
}
Subaccount Blacklist
Each access can be restricted from operating on a list of subaccounts. The blacklist is stored on the access itself — blacklisted subaccounts do not appear in subaccount listings for that access and any operation against them is rejected. The main account's own ID can be blacklisted too, which limits the access to its non-blacklisted subaccounts.
Adding and removing accounts requires admin with MFA enabled on the calling access. Listing an access's blacklist is also open to manageAccesses delegates, who change a blacklist through blacklistedSubAccountIds on Create and Update.
Add Account to Blacklist
Endpoint
URL Parameters
| Field | Type | Required | Description |
|---|---|---|---|
access-id | string | Yes | UUID of the target access. |
Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
accountId | string | Yes | UUID of the subaccount to blacklist. |
otp | string | Yes | TOTP code from the admin's authenticator app. |
Request body
{
"accountId": "55555555-5555-5555-5555-555555555555",
"otp": "999999"
}
Request example
curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/accesses/00000000-0000-0000-0000-000000000000/blacklist" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-d '{
"accountId": "55555555-5555-5555-5555-555555555555",
"otp": "999999"
}'
List Blacklisted Accounts for an Access
Endpoint
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/auth/accesses/00000000-0000-0000-0000-000000000000/blacklist" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Response
The response also says whether the access is limited to allowed subaccounts, and how many. seesSubAccountsNotAllowedToYou is true when you are limited to your own allowed subaccounts and the access is allowed one you are not: you cannot edit it.
{
"accountIds": [
"55555555-5555-5555-5555-555555555555",
"66666666-6666-6666-6666-666666666666"
],
"allowedSubAccountsOnly": true,
"allowedSubAccountsCount": 240,
"seesSubAccountsNotAllowedToYou": false
}
Remove Account from Blacklist
Endpoint
URL Parameters
| Field | Type | Required | Description |
|---|---|---|---|
access-id | string | Yes | UUID of the target access. |
account-id | string | Yes | UUID of the subaccount to un-blacklist. |
Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
otp | string | Yes | TOTP code from the admin's authenticator app. Sent in the JSON body, not the query string. |
Request example
curl -X DELETE "https://api.sandbox.avenia.io:10952/v2/auth/accesses/00000000-0000-0000-0000-000000000000/blacklist/55555555-5555-5555-5555-555555555555" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-d '{ "otp": "999999" }'
Allowed Subaccounts
The blacklist hides the subaccounts it names, so a subaccount created later is visible to every access until it is blacklisted for each one. To give an access only some subaccounts instead, create or update it with allowedSubAccountsOnly: true and the subaccounts in allowedSubAccountIds:
- Every other subaccount is hidden from the access, as a blacklisted one is: it does not appear in subaccount listings and any operation against it is rejected. A subaccount created later is hidden too.
- A subaccount the access creates itself (with
createSubAccounts) is added to its allowed subaccounts. So is one created with the access inallowedAccessIds. - The main account is not affected: blacklist its ID to hide it. The blacklist also wins over the allowed subaccounts.
- An access with allowed subaccounts, or with any blacklisted account, cannot use
subAccountId=*to search tickets across the workspace.
An invite carries the first ones in allowedSubAccountIds, at most 100. An update then adds and removes them with addAllowedSubAccountIds and removeAllowedSubAccountIds, so the list is never sent whole and has no limit:
{
"allowedSubAccountsOnly": true,
"addAllowedSubAccountIds": ["77777777-7777-7777-7777-777777777777"],
"removeAllowedSubAccountIds": ["88888888-8888-8888-8888-888888888888"],
"blacklistedSubAccountIds": ["11111111-1111-1111-1111-111111111111"]
}
With this body, and 11111111-… the main account, the access gains subaccount 77777777-…, loses 88888888-… and keeps the others it was allowed.
List the Subaccounts an Access Sees
Lists, 10 at a time and newest first, the subaccounts the access sees and you see too. For an access limited to its allowed subaccounts, those are the allowed ones. The query parameters and the response are those of List All Subaccounts: name filters by part of the name and cursor asks for the next page. Requires admin or manageAccesses.
Endpoint
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/auth/accesses/00000000-0000-0000-0000-000000000000/sub-accounts?name=store" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
The other way round, List Accesses with seesSubAccountId returns the accesses that see a subaccount.
Current Access Information
Returns the access tied to the bearer token currently calling the API — useful for sanity-checking which access (and which permissions) a given token represents. It includes the accounts blacklisted for it (blacklistedAccountIds) and whether it is limited to allowed subaccounts (allowedSubAccountsOnly).
Endpoint
Request example
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/access-info" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Common Errors
| HTTP | Reason |
|---|---|
| 400 | you need to activate your 2fa — calling access has no MFA configured. |
| 400 | you've reached the maximum number of accesses created — 100-access cap hit. |
| 400 | invalid field: email / invalid field: otp. |
| 400 | invalid field: id on delete — the target is the admin access. |
| 400 | minApprovals is required when approver accesses are provided / minApprovals cannot be greater than the number of approvers. |
| 400 | allowedSubAccountIds needs allowedSubAccountsOnly set to true / allowedSubAccountIds takes at most 100 sub-accounts / invalid field: allowedSubAccountIds. |
| 400 | addAllowedSubAccountIds and removeAllowedSubAccountIds need allowedSubAccountsOnly set to true / ... take at most 1000 sub-accounts each / sub-account <id> is both added and removed. |
| 401 | Missing or invalid bearer token. |
| 403 | requires admin or manageAccesses access — the caller is neither admin nor a delegate. |
| 403 | requires admin access — delete access and blacklist add/remove are admin-only. |
| 403 | requires admin, manageAccesses or createSubAccounts access — on List Restricted Accesses. |
| 403 | only the admin can grant the manageAccesses permission |
| 403 | you cannot grant the <permission> permission, which you do not have |
| 403 | the access must keep <permission>, which applies to you |
| 403 | the access must not see account <id>, which is hidden from you |
| 403 | the access must see only sub-accounts allowed to it, as you do / the access must not see sub-account <id>, which is not allowed to you |
| 403 | you cannot approve the operations of an access you invite |
| 403 | the access must need the same approvals as you: your approvers and minimum approvals |
| 403 | you cannot edit the admin access / you cannot edit your own access / you cannot edit an access that manages accesses |
| 403 | you cannot edit an access with permissions you do not have |
| 403 | only the admin can change multi-signature settings |
| 403 | On Validate Access: the access that sent this invite no longer exists / the access that sent this invite can no longer manage accesses / this invite grants more than the access that sent it can grant now |
The delegate rules are explained in Delegated Access Management. Ticket permissions (convert, payOut, manageAssets) are refused on the ticket endpoints, not here.
Conclusion
You now have the complete API surface for managing accesses on Avenia API:
- ✅ Create + validate a new access (two-step email flow)
- ✅ Granular permissions (pay-out, view-only, convert, manage assets, markup, beneficiary, enforce-allowed-beneficiaries, create subaccounts)
- ✅ Delegated access management and multi-signature approval
- ✅ Subaccount blacklist per access
- ✅ List / inspect / update / delete accesses
- ✅ Inspect the current bearer's access