Mercury (API Token)
Connect Mercury accounts using a scoped API token
Overview
Section titled “Overview”| Property | Value |
|---|---|
| Template ID | mercury |
| Category | Finance |
| Credential Type | Bearer Token |
The managed Mercury SDK accepts API-token managed secrets and partner OAuth connections.
Step 1: Get credentials
Section titled “Step 1: Get credentials”- Sign in to Mercury and open All Settings → Tokens.
- Select Create Token, name it, and choose Read Only, Read and Write, or Custom permissions for the required operations.
- Copy the complete token, including a
secret-token:prefix if present. - For a write token, configure the IP whitelist Mercury requires for your integration.
Custom token scopes cannot be edited. Create a replacement token to change them. Mercury can delete unused tokens after 45 days and downgrade their permissions according to its token security policies.
Step 2: Add to Alter
Section titled “Step 2: Add to Alter”In your application in the Developer Portal, open Managed Secrets, add Mercury, paste the token and save. Restrict its allowed hosts and create a system grant for the application or agent.
alter managed-secrets set-allowed-hosts <secret> --host api.mercury.comCard PAN/CVC retrieval uses the separate vault-api.mercury.com host. Include that host only when the application needs it. For sandbox, create a separate token at sandbox.mercury.com and restrict its allowed host to api-sandbox.mercury.com. Alter selects the environment from these saved host restrictions and refuses mixed production/sandbox restrictions. Mercury documents no sandbox Vault API origin.
Custom scopes can omit any particular read endpoint, so there is no universal token verification request. Alter reports save-time verification as skipped; confirm access with an operation that the token permits.
Using in code
Section titled “Using in code”from alter_sdk_mercury import MercuryIntegration
client = MercuryIntegration(alter_app, {"grant_id": "YOUR_GRANT_ID"})result = await (await client.accounts.get_accounts({})).wait()print(result.body_json())See Mercury’s getting started guide, API token security policies, sandbox guide, and Vault API reference.
Policy-cataloged operations
Section titled “Policy-cataloged operations”| Operation ID | Families | Method | Provider path | Notes |
|---|---|---|---|---|
mercury:getAccountCards | read | GET | /api/v1/account/{accountId}/cards | — |
mercury:requestSendMoney | payment, send, write | POST | /api/v1/account/{accountId}/request-send-money | — |
mercury:getAccountStatements | read | GET | /api/v1/account/{accountId}/statements | — |
mercury:getTransaction | read | GET | /api/v1/account/{accountId}/transaction/{transactionId} | — |
mercury:listAccountTransactions | read | GET | /api/v1/account/{accountId}/transactions | — |
mercury:createTransaction | payment, send, write | POST | /api/v1/account/{accountId}/transactions | — |
mercury:getAccounts | read | GET | /api/v1/accounts | — |
mercury:createInternalTransfer | payment, write | POST | /api/v1/transfer | — |
mercury:getRecipient | read | GET | /api/v1/recipient/{recipientId} | allowed; its secret is never stored in a payload capture |
mercury:getRecipients | read | GET | /api/v1/recipients | allowed; its secret is never stored in a payload capture |
mercury:updateRecipient | payment, write | POST | /api/v1/recipient/{recipientId} | also payment when (body.@EditRecipientRequest.address is present ({"missing”: false, “null”: true})) or (body.@EditRecipientRequest.checkInfo is present ({"missing”: false, “null”: true})) or (body.@EditRecipientRequest.domesticWireRoutingInfo is present ({"missing”: false, “null”: true})) or (body.@EditRecipientRequest.electronicRoutingInfo is present ({"missing”: false, “null”: true})) or (body.@EditRecipientRequest.realTimePaymentRoutingInfo is present ({"missing”: false, “null”: true})) or (body.@EditRecipientRequest.name is present ({"missing”: false, “null”: true, “type”: “string"})); the family column is the upper bound; base families are write; unreadable or invalid effect inputs are refused when the request condition reads them; allowed; its secret is never stored in a payload capture |
mercury:createRecipient | write | POST | /api/v1/recipients | allowed; its secret is never stored in a payload capture |
mercury:uploadRecipientAttachment | write | POST | /api/v1/recipient/{recipientId}/attachments | — |
mercury:listRecipientsAttachments | read | GET | /api/v1/recipients/attachments | allowed; its secret is never stored in a payload capture |
mercury:deleteRecipient | delete | DELETE | /api/v1/recipient/{recipientId} | — |
mercury:createRecipientInvite | payment, send, write | POST | /api/v1/recipients/invites | also send when body.@CreateRecipientInviteApiRequest.sendEmail is one of [true] ({"missing”: null, “null”: null, “type”: “boolean"}); also payment when (body.@CreateRecipientInviteApiRequest.recipientId is present ({"missing”: false, “null”: false, “type”: “string"})) and (body.@CreateRecipientInviteApiRequest.name is present ({"missing”: false, “null”: true, “type”: “string"})); the family column is the upper bound; base families are write; unreadable or invalid effect inputs are refused when the request condition reads them; allowed; its secret is never stored in a payload capture |
mercury:getRecipientInvite | read | GET | /api/v1/recipients/invites/{inviteId} | allowed; its secret is never stored in a payload capture |
mercury:listRecipientInvites | read | GET | /api/v1/recipients/invites | allowed; its secret is never stored in a payload capture |
mercury:deleteRecipientInvite | delete | DELETE | /api/v1/recipients/invites/{inviteId} | — |
mercury:listSendMoneyApprovalRequests | read | GET | /api/v1/request-send-money | — |
mercury:getSendMoneyApprovalRequest | read | GET | /api/v1/request-send-money/{requestId} | — |
mercury:requestTransferMoney | payment, write | POST | /api/v1/request-transfer | — |
mercury:listTransferMoneyApprovalRequests | read | GET | /api/v1/request-transfer | — |
mercury:getTransferMoneyApprovalRequest | read | GET | /api/v1/request-transfer/{requestId} | — |
mercury:getTreasury | read | GET | /api/v1/treasury | — |
mercury:getTreasuryTransactions | read | GET | /api/v1/treasury/{treasuryId}/transactions | — |
mercury:getTreasuryStatements | read | GET | /api/v1/treasury/{treasuryId}/statements | — |
mercury:getStatementPdf | read | GET | /api/v1/statements/{statementId}/pdf | — |
mercury:updateTransaction | write | PATCH | /api/v1/transaction/{transactionId} | — |
mercury:listTransactions | read | GET | /api/v1/transactions | — |
mercury:getTransactionById | read | GET | /api/v1/transaction/{transactionId} | — |
mercury:uploadTransactionAttachment | write | POST | /api/v1/transaction/{transactionId}/attachments | — |
mercury:listCategories | read | GET | /api/v1/categories | — |
mercury:createCategory | write | POST | /api/v1/categories | — |
mercury:editCategory | write | POST | /api/v1/categories/{expenseCategoryId} | — |
mercury:deleteCategory | delete | DELETE | /api/v1/categories/{expenseCategoryId} | — |
mercury:listMerchants | read | GET | /api/v1/merchants | — |
mercury:listCredit | read | GET | /api/v1/credit | — |
mercury:getCreditAccountStatements | read | GET | /api/v1/credit/{accountId}/statements | — |
mercury:getOrganization | read | GET | /api/v1/organization | — |
mercury:getAttachment | read | GET | /api/v1/ar/attachments/{attachmentId} | allowed; its secret is never stored in a payload capture |
mercury:listCustomers | read | GET | /api/v1/ar/customers | — |
mercury:createCustomer | write | POST | /api/v1/ar/customers | — |
mercury:deleteCustomer | delete | DELETE | /api/v1/ar/customers/{customerId} | — |
mercury:getCustomer | read | GET | /api/v1/ar/customers/{customerId} | — |
mercury:updateCustomer | payment, send, write | POST | /api/v1/ar/customers/{customerId} | also send when body.@ApiV1ArCustomerUpdateRequest.resendOpenInvoices is one of [true] ({"missing”: null, “null”: null, “type”: “boolean"}); the family column is the upper bound; base families are write, payment; unreadable or invalid effect inputs are refused when the request condition reads them |
mercury:listInvoices | read | GET | /api/v1/ar/invoices | allowed; its secret is never stored in a payload capture |
mercury:createInvoice | payment, send, write | POST | /api/v1/ar/invoices | also send when (body.@ApiV1ArInvoiceCreateRequest.sendEmailOption is one of [“SendNow”] ({"missing”: true, “null”: null, “type”: “string”, “valid_values”: [“DontSend”, “SendNow"]})) or (body.@ApiV1ArInvoiceCreateRequest.ccEmails is nonempty ({"missing”: null, “null”: null, “type”: “array"})); the family column is the upper bound; base families are payment, write; unreadable or invalid effect inputs are refused when the request condition reads them; allowed; its secret is never stored in a payload capture |
mercury:getInvoice | read | GET | /api/v1/ar/invoices/{invoiceId} | allowed; its secret is never stored in a payload capture |
mercury:updateInvoice | payment, send, write | POST | /api/v1/ar/invoices/{invoiceId} | also send when body.@ApiV1ArInvoiceUpdateRequest.ccEmails is nonempty ({"missing”: null, “null”: null, “type”: “array"}); the family column is the upper bound; base families are payment, write; unreadable or invalid effect inputs are refused when the request condition reads them; allowed; its secret is never stored in a payload capture |
mercury:cancelInvoice | delete, payment | POST | /api/v1/ar/invoices/{invoiceId}/cancel | — |
mercury:listInvoiceAttachments | read | GET | /api/v1/ar/invoices/{invoiceId}/attachments | allowed; its secret is never stored in a payload capture |
mercury:getInvoicePdf | read | GET | /api/v1/ar/invoices/{invoiceId}/pdf | — |
mercury:getEvents | read | GET | /api/v1/events | — |
mercury:getEvent | read | GET | /api/v1/events/{eventId} | — |
mercury:createWebhook | admin, send, write | POST | /api/v1/webhooks | allowed; its secret is never stored in a payload capture; delivery address in policy parameter url |
mercury:updateWebhook | admin, delete, send, write | POST | /api/v1/webhooks/{webhookEndpointId} | also delete when body.@UpdateWebhookParams.status is one of [“paused”] ({"missing”: false, “null”: null, “type”: “string”, “valid_values”: [“active”, “paused"]}); also send when (body.@UpdateWebhookParams.url is non-null ({"missing”: false, “null”: null, “type”: “string"})) or (body.@UpdateWebhookParams.status is one of [“active”] ({"missing”: false, “null”: null, “type”: “string”, “valid_values”: [“active”, “paused"]})) or (body.@UpdateWebhookParams.eventTypes is present ({"missing”: false, “null”: true, “type”: “array"})) or (body.@UpdateWebhookParams.filterPaths is present ({"missing”: false, “null”: true, “type”: “array"})); the family column is the upper bound; base families are write, admin; unreadable or invalid effect inputs are refused when the request condition reads them; delivery address in policy parameter url |
mercury:verifyWebhook | send | POST | /api/v1/webhooks/{webhookEndpointId}/verify | — |
mercury:getWebhook | read | GET | /api/v1/webhooks/{webhookEndpointId} | — |
mercury:getWebhooks | read | GET | /api/v1/webhooks | — |
mercury:deleteWebhook | admin, delete | DELETE | /api/v1/webhooks/{webhookEndpointId} | — |
mercury:getUser | read | GET | /api/v1/users/{userId} | — |
mercury:getUsers | read | GET | /api/v1/users | — |
mercury:getSafeRequests | read | GET | /api/v1/safes | — |
mercury:getSafeRequest | read | GET | /api/v1/safes/{safeRequestId} | — |
mercury:getSafeRequestDocument | read | GET | /api/v1/safes/{safeRequestId}/document | — |
mercury:listReceipts | read | GET | /api/v1/spend/receipts | — |
mercury:createReceiptUploadUrl | write | POST | /api/v1/spend/receipts | allowed; its secret is never stored in a payload capture |
mercury:getReceipt | read | GET | /api/v1/spend/receipts/{receiptId} | — |
mercury:matchReceipt | write | POST | /api/v1/spend/receipts/{receiptId}/match | — |
mercury:listBudgets | read | GET | /api/v1/spend/budgets | — |
mercury:createBudget | write | POST | /api/v1/spend/budgets | — |
mercury:getBudget | read | GET | /api/v1/spend/budgets/{budgetId} | — |
mercury:updateBudget | payment, write | POST | /api/v1/spend/budgets/{budgetId} | also payment when (body.@ApiV1UpdateBudgetRequest.amountPerUserPerPeriod is non-null ({"missing”: false, “null”: false, “type”: “number"})) or (body.@ApiV1UpdateBudgetRequest.frequency is non-null ({"missing”: false, “null”: false, “type”: “string”, “valid_values”: [“oneTime”, “daily”, “weekly”, “monthly”, “yearly"]})) or (body.@ApiV1UpdateBudgetRequest.startDate is non-null ({"missing”: false, “null”: false, “type”: “string"})) or (body.@ApiV1UpdateBudgetRequest.endDate is non-null ({"missing”: false, “null”: false, “type”: “string"})); the family column is the upper bound; base families are write; unreadable or invalid effect inputs are refused when the request condition reads them |
mercury:archiveBudget | delete | POST | /api/v1/spend/budgets/{budgetId}/archive | — |
mercury:assignTransactionToBudget | write | POST | /api/v1/spend/budgets/{budgetId}/assign-transaction | — |
mercury:getBudgetExpenditures | read | GET | /api/v1/spend/budgets/{budgetId}/expenditures | — |
mercury:getBudgetMembers | read | GET | /api/v1/spend/budgets/{budgetId}/members | — |
mercury:listCards | read | GET | /api/v1/cards | — |
mercury:createCard | payment, write | POST | /api/v1/cards | — |
mercury:getCard | read | GET | /api/v1/cards/{cardId} | — |
mercury:updateCard | payment, write | POST | /api/v1/cards/{cardId} | also payment when body.@UpdateCardRequest.spendLimit is present ({"missing”: false, “null”: true}); the family column is the upper bound; base families are write; unreadable or invalid effect inputs are refused when the request condition reads them |
mercury:cancelCard | delete | POST | /api/v1/cards/{cardId}/cancel | — |
mercury:freezeCard | delete | POST | /api/v1/cards/{cardId}/freeze | — |
mercury:unfreezeCard | payment, write | POST | /api/v1/cards/{cardId}/unfreeze | — |
mercury:revealCardPan | read | GET | /api/v1/cards/{cardId}/reveal | — |
mercury:getAutoTransferRules | read | GET | /api/v1/auto-transfer-rules | — |
auth:authorization_endpoint | admin, send, write | GET | /oauth2/auth | refused by default: hands the caller a provider credential, or revokes the connection’s own (a credential_minting rule can allow it); served by the provider but absent from its published spec |
auth:token_endpoint | admin, write | POST | /oauth2/token | refused by default: hands the caller a provider credential, or revokes the connection’s own (a credential_minting rule can allow it); served by the provider but absent from its published spec |
auth:userinfo_endpoint | read | GET | /userinfo | served by the provider but absent from its published spec |
auth:revocation_endpoint | admin, delete | POST | /oauth2/revoke | refused by default: hands the caller a provider credential, or revokes the connection’s own (a credential_minting rule can allow it); served by the provider but absent from its published spec |
auth:device_authorization_endpoint | write | POST | /oauth2/device/auth | allowed; its secret is never stored in a payload capture; served by the provider but absent from its published spec |
auth:end_session_endpoint | delete, send | GET | /oauth2/sessions/logout | served by the provider but absent from its published spec |
auth:jwks_uri | read | GET | /.well-known/jwks.json | served by the provider but absent from its published spec |
auth:credentials_endpoint_draft_00 | admin, read, write | POST | /credentials | refused by default when (not (a complete, unambiguous JSON object containing only format=jwt_vc_json and a type array of exactly VerifiableCredential and UserCredential in either order, with no proof or additional member)); a credential_minting rule can allow it; also admin, read when not (a complete, unambiguous JSON object containing only format=jwt_vc_json and a type array of exactly VerifiableCredential and UserCredential in either order, with no proof or additional member); the family column is the upper bound; base families are write; unreadable or invalid effect inputs are refused when the request condition reads them; its secret is never stored in a payload capture; served by the provider but absent from its published spec |
auth:authorization_endpoint:post | admin, send, write | POST | /oauth2/auth | refused by default: hands the caller a provider credential, or revokes the connection’s own (a credential_minting rule can allow it); served by the provider but absent from its published spec |
auth:userinfo_endpoint:post | read | POST | /userinfo | served by the provider but absent from its published spec |
auth:end_session_endpoint:post | delete, send | POST | /oauth2/sessions/logout | served by the provider but absent from its published spec |
mercury:createProduct | write | POST | /api/v1/ar/products | — |
mercury:listProducts | read | GET | /api/v1/ar/products | — |
mercury:deleteProduct | delete | DELETE | /api/v1/ar/products/{productId} | — |