Grant Account Access
Grants one of the member’s users access to this account. UDX records the grant immediately; it starts pending while exchange access is set up, so poll the account’s grants until the new grant is active.
POST
/portfolio/accounts/{account_id}/grantsAuthorization
UDX-Access-KeyAPI key · headerrequiredOpaque API key ID.
UDX-Access-TimestampAPI key · headerrequiredUnix time in milliseconds, within 30 seconds of server time.
UDX-Access-SignatureAPI key · headerrequiredStandard-base64 RSA-PSS/SHA-256 signature with a 32-byte salt. Sign `timestamp + METHOD + path`; for requests with a body, append `hex(SHA256(body))`; append `UDX-Idempotency-Key` when it is present.
or
AuthorizationBearer token (JWT) · headerrequiredBearer token for an active signed-in UDX user.
Path parameters
account_idEntityIdrequiredThe public identifier of the account whose grants are managed.
Header parameters
UDX-VersionstringDated API version (YYYY-MM-DD). Omit to use the oldest supported version. An unknown version returns `400`.
max length 10
UDX-Idempotency-KeystringOptional client-generated key that makes a mutation safe to retry. Reuse it only for a byte-identical retry. When present, it is included in the request signature; omitting it disables UDX idempotency for that request.
min length 1 · max length 255
Request body
requiredapplication/jsonuser_idobjectrequiredThe public identifier of the member's user to grant access to.
Show propertiesHide properties
objectResponses
202The grant was created. Reusing the creation idempotency key replays this response instead of creating another grant.
grantGrantrequiredA user's authorization to reach one of the member's accounts. The account is the one addressed in the request path.
Show propertiesHide properties
idobjectrequiredThe grant's public identifier.
Show propertiesHide properties
objectuser_idobjectrequiredThe user this grant authorizes.
Show propertiesHide properties
objectstatusstringrequiredReadiness of the granted access: pending (exchange setup is still running), active (the grant is fully usable), or failed (setup failed and UDX is retrying it).
Allowed:
pendingactivefailedcreated_atstring<date-time>requiredUDX timestamps use RFC 3339; responses use UTC with exactly six fractional digits. When access was granted.
max length 40
400The request doesn't conform to this spec.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
401No valid credential was provided.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
403The credential lacks the `grants:manage` scope or is restricted to one account.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
404The account doesn't exist or the caller holds no grant on it. The two cases are deliberately indistinguishable.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
409The user already holds a grant on this account, or a request with this idempotency key is still in progress.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
422This key belongs to a different request.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
429The Member's request rate is exhausted. Wait for `Retry-After`.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
500Something went wrong on UDX's side.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
503Request admission is unavailable. Retry later.
typestring<uri-reference>A stable URI identifying the error's general category. Usually absent (equivalent to "about:blank" per the RFC); documented rate controls use closed URN values so callers can distinguish same-status retry causes without parsing localized prose.
max length 2048
titlestringrequiredA localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
max length 40
statusintegerrequiredThe HTTP status code, repeated from the response itself.
detailstringA localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
max length 500
instancestring<uri-reference>An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
max length 100
Request
curl -X POST "https://{hostname}/portfolio/accounts/6820943174116859281/grants" \
-H "UDX-Access-Key: API_KEY_ID" \
-H "UDX-Access-Timestamp: UNIX_MILLISECONDS" \
-H "UDX-Access-Signature: BASE64_SIGNATURE" \
-H "Content-Type: application/json" \
-d '{
"user_id": "1194626289313312742"
}'const response = await fetch("https://{hostname}/portfolio/accounts/6820943174116859281/grants", {
method: "POST",
headers: {
"UDX-Access-Key": "API_KEY_ID",
"UDX-Access-Timestamp": "UNIX_MILLISECONDS",
"UDX-Access-Signature": "BASE64_SIGNATURE",
"Content-Type": "application/json"
},
body: JSON.stringify({
"user_id": "1194626289313312742"
})
});import requests
response = requests.post(
"https://{hostname}/portfolio/accounts/6820943174116859281/grants",
headers={
"UDX-Access-Key": "API_KEY_ID",
"UDX-Access-Timestamp": "UNIX_MILLISECONDS",
"UDX-Access-Signature": "BASE64_SIGNATURE",
"Content-Type": "application/json"
},
json={
"user_id": "1194626289313312742"
},
)Response
{
"grant": {
"id": "5822799328558517173",
"user_id": "1194626289313312742",
"status": "pending",
"created_at": "2026-08-20T09:30:00.000000Z"
}
}{
"title": "Bad Request",
"status": 400,
"detail": "request did not pass validation",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"title": "Unauthorized",
"status": 401,
"detail": "invalid authentication credentials",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"title": "Forbidden",
"status": 403,
"detail": "insufficient permissions",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"title": "Not Found",
"status": 404,
"detail": "account not found",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"title": "Conflict",
"status": 409,
"detail": "user already holds a grant on this account",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"title": "Unprocessable Entity",
"status": 422,
"detail": "UDX-Idempotency-Key was already used for a different request",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"type": "urn:udx:problem:member-rate-limit-exceeded",
"title": "Too Many Requests",
"status": 429,
"detail": "this member has temporarily exceeded its request rate",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"title": "Internal Server Error",
"status": 500,
"detail": "internal error",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}{
"type": "urn:udx:problem:request-admission-unavailable",
"title": "Service Unavailable",
"status": 503,
"detail": "request admission is temporarily unavailable",
"instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}