Skip to main content

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.

warning

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.

info

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.

FieldTypeDefault on createDescription
adminbooleanfalseRead-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.
viewOnlybooleanfalseRead-only access. When true, the access can list balances and transactions but cannot move funds or change anything.
payOutbooleanfalseAllows 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.
convertbooleantrue ¹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.
payInbooleantrue ¹Pay-in flag. Stored on the access and returned on GET.
onChainbooleantrue ¹On-chain flag. Stored on the access and returned on GET. On-chain transfers to external wallets are governed by payOut.
manageAssetsbooleantrueRequired 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.
markupbooleantrueAllows the access to set/override quote markup.
beneficiarybooleantrueAllows the access to manage beneficiaries (bank accounts, wallets).
enforceAllowedBeneficiariesbooleanfalseWhen true, the access can only operate on a curated allow-list of beneficiaries.
createSubAccountsbooleantrueAllows the access to create subaccounts. false refuses subaccount creation with 403.
manageAccessesbooleanfalseLets a non-admin access list, create and edit other accesses. Only the admin can grant or revoke it. See Delegated Access Management.
operationRequesterbooleanfalsePuts the access under multi-signature approval. See Multi-Signature Approval.
operationApproverbooleanfalseAllows 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.

OperationNeeds convert
BRL (PIX) → BRLA, BRLA → BRL (PIX)No
USD (WIRE) → USDCNo
USDC ↔ USDTNo
BRL (PIX) → USDC, BRLA → USDTYes
EoD trade (BRLA ↔ USDC)Yes
Payment session paid in BRL, crediting USDCYes

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.

note

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:

FieldTypeDescription
blacklistedSubAccountIdsarray of stringUUIDs of accounts this access is not allowed to operate on. See Subaccount Blacklist.
allowedSubAccountsOnlybooleantrue limits the access to the subaccounts in allowedSubAccountIds, so a subaccount created later stays hidden from it. See Allowed Subaccounts.
allowedSubAccountIdsarray of stringPOST only, with allowedSubAccountsOnly: true: UUIDs of the subaccounts the access may operate on. At most 100.
addAllowedSubAccountIdsarray of stringPATCH only, with allowedSubAccountsOnly: true: UUIDs of the subaccounts added to the allowed ones. At most 1000 per request.
removeAllowedSubAccountIdsarray of stringPATCH only, with allowedSubAccountsOnly: true: UUIDs of the subaccounts taken off the allowed ones. At most 1000 per request.
approverAccessIdsarray of stringOnly for operationRequester accesses: UUIDs of the accesses that can approve its operations.
minApprovalsintegerOnly 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.
multisigNotificationsbooleanPATCH 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:

EndpointDelegateAdmin
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:

RuleApplies toMessage
Only the admin grants manageAccesses. Sending manageAccesses: false is accepted.POST, PATCHonly 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, PATCHyou 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, PATCHthe 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, PATCHthe 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, PATCHthe 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.POSTyou 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.POSTthe 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.PATCHyou 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.PATCHyou 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.PATCHonly 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​

POSThttps://api.sandbox.avenia.io:10952/v2/auth/accesses/

Body Parameters​

FieldTypeRequiredDescription
otpstringYesTOTP code from the caller's authenticator app.
emailstringYesEmail of the new access. Must be a valid address, ≤ 256 characters.
permissionsobjectYesPermission flags. See Permissions Reference.
permissions.payOutbooleanNoDefaults to false.
permissions.viewOnlybooleanNoDefaults to false.
permissions.convertbooleanNoDefaults to true (false if viewOnly).
permissions.payInbooleanNoDefaults to true (false if viewOnly).
permissions.onChainbooleanNoDefaults to true (false if viewOnly).
permissions.manageAssetsbooleanNoDefaults to true.
permissions.markupbooleanNoDefaults to true.
permissions.beneficiarybooleanNoDefaults to true.
permissions.enforceAllowedBeneficiariesbooleanNoDefaults to false.
permissions.createSubAccountsbooleanNoDefaults to true.
permissions.manageAccessesbooleanNoDefaults to false. Only the admin access can set it to true.
permissions.operationRequesterbooleanNoDefaults to false.
permissions.operationApproverbooleanNoDefaults to false.
blacklistedSubAccountIdsarray of stringNoAccount UUIDs this access cannot operate on.
allowedSubAccountsOnlybooleanNoDefaults to false. See Allowed Subaccounts.
allowedSubAccountIdsarray of stringNoSubaccount UUIDs the access may operate on. Only with allowedSubAccountsOnly: true.
approverAccessIdsarray of stringNoApprovers of a requester access. Requires minApprovals.
minApprovalsintegerNoApprovals needed for a requester access.

Request body​

JSON
{
"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
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​

POSThttps://api.sandbox.avenia.io:10952/v2/auth/accesses/validate/{token}

URL Parameters​

FieldTypeDescription
tokenstringEmail token from the invitation link (10-min TTL).

Body Parameters​

FieldTypeRequiredDescription
passwordstringYesNew password for the access (1–64 characters).
confirmPasswordstringYesMust match password.

Request body​

JSON
{
"password": "UseAStrongPassword123!",
"confirmPassword": "UseAStrongPassword123!"
}

Request example​

cURL
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:

ConditionMessage
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​

GEThttps://api.sandbox.avenia.io:10952/v2/auth/accesses/

Query Parameters​

FieldTypeDescription
emailstringFilter by email (exact match; emails are stored in lowercase).
payOutbooleanFilter by payOut permission.
viewOnlybooleanFilter by viewOnly permission.
convertbooleanFilter by convert permission.
payInbooleanFilter by payIn permission.
onChainbooleanFilter by onChain permission.
createdAfterint64Unix epoch timestamp in milliseconds (UTC) — e.g. 1700000000000. Returns accesses created on or after this instant (createdAt >= createdAfter).
createdBeforeint64Unix epoch timestamp in milliseconds (UTC) — e.g. 1800000000000. Returns accesses created on or before this instant (createdAt <= createdBefore).
seesSubAccountIdstring (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.
Timestamp format

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
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​

JSON
{
"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​

GEThttps://api.sandbox.avenia.io:10952/v2/auth/accesses/{access-id}

URL Parameters​

FieldTypeRequiredDescription
access-idstringYesUUID of an existing access.

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/auth/accesses/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response​

JSON
{
"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​

PATCHhttps://api.sandbox.avenia.io:10952/v2/auth/accesses/

Body Parameters​

FieldTypeRequiredDescription
idstringYesUUID of the access to update.
otpstringYesTOTP code from the caller's authenticator app.
permissionsobjectYesSame fields as in Create. See below for what an omitted field does.
blacklistedSubAccountIdsarray of stringNoReplaces the access blacklist; [] clears it. Use the dedicated Blacklist endpoints for incremental updates.
allowedSubAccountsOnlybooleanNotrue 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.
addAllowedSubAccountIdsarray of stringNoOnly with allowedSubAccountsOnly: true: subaccounts to allow. One already allowed is left as it is.
removeAllowedSubAccountIdsarray of stringNoOnly with allowedSubAccountsOnly: true: subaccounts to take off. A subaccount cannot be in both lists.
approverAccessIdsarray of stringNoReplaces the approvers of a requester access.
minApprovalsintegerNoApprovals needed for a requester access.
multisigNotificationsbooleanNoTurns the multi-signature notification emails of the access on or off.
Omitted fields

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-level blacklistedSubAccountIds, allowedSubAccountsOnly (with the allowed subaccounts), approverAccessIds, minApprovals and multisigNotifications.
  • Is set to false: payOut, viewOnly, markup, beneficiary, enforceAllowedBeneficiaries, operationRequester and operationApprover.

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​

JSON
{
"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
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​

DELETEhttps://api.sandbox.avenia.io:10952/v2/auth/accesses/{access-id}?otp=999999

URL Parameters​

FieldTypeRequiredDescription
access-idstringYesUUID of the access to delete.

Query Parameters​

FieldTypeRequiredDescription
otpstringYesTOTP code from the authenticator app.

Request example​

cURL
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​

GEThttps://api.sandbox.avenia.io:10952/v2/auth/accesses/approvers

Request example​

cURL
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​

GEThttps://api.sandbox.avenia.io:10952/v2/auth/accesses/restricted

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/auth/accesses/restricted" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Response​

JSON
{
"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​

POSThttps://api.sandbox.avenia.io:10952/v2/auth/accesses/{access-id}/blacklist

URL Parameters​

FieldTypeRequiredDescription
access-idstringYesUUID of the target access.

Body Parameters​

FieldTypeRequiredDescription
accountIdstringYesUUID of the subaccount to blacklist.
otpstringYesTOTP code from the admin's authenticator app.

Request body​

JSON
{
"accountId": "55555555-5555-5555-5555-555555555555",
"otp": "999999"
}

Request example​

cURL
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​

GEThttps://api.sandbox.avenia.io:10952/v2/auth/accesses/{access-id}/blacklist

Request example​

cURL
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.

JSON
{
"accountIds": [
"55555555-5555-5555-5555-555555555555",
"66666666-6666-6666-6666-666666666666"
],
"allowedSubAccountsOnly": true,
"allowedSubAccountsCount": 240,
"seesSubAccountsNotAllowedToYou": false
}

Remove Account from Blacklist​

Endpoint​

DELETEhttps://api.sandbox.avenia.io:10952/v2/auth/accesses/{access-id}/blacklist/{account-id}

URL Parameters​

FieldTypeRequiredDescription
access-idstringYesUUID of the target access.
account-idstringYesUUID of the subaccount to un-blacklist.

Body Parameters​

FieldTypeRequiredDescription
otpstringYesTOTP code from the admin's authenticator app. Sent in the JSON body, not the query string.

Request example​

cURL
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 in allowedAccessIds.
  • 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:

JSON
{
"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​

GEThttps://api.sandbox.avenia.io:10952/v2/auth/accesses/{access-id}/sub-accounts

Request example​

cURL
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​

GEThttps://api.sandbox.avenia.io:10952/v2/account/access-info

Request example​

cURL
curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/access-info" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Common Errors​

HTTPReason
400you need to activate your 2fa — calling access has no MFA configured.
400you've reached the maximum number of accesses created — 100-access cap hit.
400invalid field: email / invalid field: otp.
400invalid field: id on delete — the target is the admin access.
400minApprovals is required when approver accesses are provided / minApprovals cannot be greater than the number of approvers.
400allowedSubAccountIds needs allowedSubAccountsOnly set to true / allowedSubAccountIds takes at most 100 sub-accounts / invalid field: allowedSubAccountIds.
400addAllowedSubAccountIds and removeAllowedSubAccountIds need allowedSubAccountsOnly set to true / ... take at most 1000 sub-accounts each / sub-account <id> is both added and removed.
401Missing or invalid bearer token.
403requires admin or manageAccesses access — the caller is neither admin nor a delegate.
403requires admin access — delete access and blacklist add/remove are admin-only.
403requires admin, manageAccesses or createSubAccounts access — on List Restricted Accesses.
403only the admin can grant the manageAccesses permission
403you cannot grant the <permission> permission, which you do not have
403the access must keep <permission>, which applies to you
403the access must not see account <id>, which is hidden from you
403the 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
403you cannot approve the operations of an access you invite
403the access must need the same approvals as you: your approvers and minimum approvals
403you cannot edit the admin access / you cannot edit your own access / you cannot edit an access that manages accesses
403you cannot edit an access with permissions you do not have
403only the admin can change multi-signature settings
403On 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