Overview

The Slash API lets you build custom workflows on top of your Slash account, including reading balances and transactions, managing cards, moving funds, and receiving real-time event notifications through webhooks.

This guide explains the core concepts every developer should understand before building with Slash: API authentication, API key security, webhook delivery, webhook verification, and common error responses.

Before you begin

To use the Slash API, you need:

A Slash account with API access enabled
Permission to create or manage API keys for the relevant business entity
An API key with the scopes required for the actions your integration needs
A secure place to store secrets, such as an environment variable manager or secrets vault

How API authentication works

Slash API requests must be authenticated. Authentication tells Slash which account or integration is making the request and which permissions apply.

For most direct API integrations, you authenticate with a Slash API key. Create the key from your Slash dashboard, give it a descriptive name, and select the scopes your integration needs.

When making requests, include your API key using the authentication method supported by the endpoint or integration you are using. For Slash MCP connections, the key can be passed in the X-API-Key header, or as a URL query parameter if your client only supports URL-based configuration.

If you are building directly against the public API, follow the authentication instructions in the current API documentation for the endpoint you are calling.

API key best practices

Treat API keys like passwords. Anyone with access to an API key may be able to access account data or perform actions allowed by that key's scopes.

Use least-privilege scopes. Only grant the permissions your integration actually needs.
Create separate keys for separate systems. Use one key for each app, server, or AI client so you can revoke access without disrupting unrelated integrations.
Store keys securely. Do not hardcode keys in frontend code, mobile apps, public repositories, or shared documents.
Rotate keys when needed. Replace keys if an employee leaves, a vendor no longer needs access, or you suspect a key was exposed.
Revoke unused keys. Remove keys for retired integrations or old test environments.

Understanding scopes and permissions

Scopes define what an API key can do. For example, one key may be allowed to read account balances, while another may be allowed to create cards or move funds.

If a request fails even though the key is valid, the key may not have the required scope for that endpoint. Review the scopes assigned to the key and compare them with the action you are trying to perform.

How webhooks work

Webhooks let Slash notify your system when something changes, instead of requiring you to repeatedly poll the API. When an event occurs, Slash sends an HTTP request to the webhook endpoint you configured.

Webhook events include metadata about what changed, such as the event type, event ID, and related entity ID. They do not always include the full current state of the entity. To get the latest data, make a follow-up API request using the ID included in the event.

Examples of webhook event types include:

card.update— Triggered when a card's details or status changes
card.delete— Triggered when a card is deleted
card_creation.event— Triggered when a new card is created
aggregated_transaction.create— Triggered when a new transaction is created
aggregated_transaction.update— Triggered when a transaction's status or details change

Setting up a webhook endpoint

To receive webhooks, create an HTTPS endpoint on your server and register it with Slash. Your endpoint should be able to receive POST requests, verify that they came from Slash, process the event, and return a successful response quickly.

At a high level:

Create a webhook endpoint URL in your application.
Register the endpoint with Slash using the webhook API.
Verify webhook signatures on every request.
Return a 2xx response after accepting the event.
Use follow-up API calls when you need the latest full object data.

Verifying webhook signatures

Every webhook request includes a slash-webhook-signature header. Verify this signature using Slash's public RSA key before trusting the event.

Signature verification helps confirm that:

The request came from Slash
The payload was not modified in transit
Your system does not process forged or replayed webhook data as if it were real

Important: Do not rely only on IP allowlists or secret URLs. Always verify webhook signatures if your integration uses webhooks to trigger business logic.

Webhook delivery and retries

Your webhook endpoint should respond with a 2xx status code within 10 seconds. If your endpoint does not respond successfully, Slash treats the delivery as failed and may retry delivery.

To make webhook handling reliable:

Respond quickly. Acknowledge the event first, then process longer work asynchronously if possible.
Make processing idempotent. Store event IDs and avoid processing the same event twice if it is retried.
Handle events out of order. Use follow-up API requests to fetch the current state before making final decisions.
Monitor failures. Log failed deliveries, signature verification failures, and unexpected event types.

Common API error codes

Slash API responses use HTTP status codes to describe the result of a request. Exact response bodies may vary by endpoint, but these are the most common categories to check:

200 or 201— The request succeeded.
400— The request was invalid. Check required fields, field formats, filters, IDs, and request body structure.
401— Authentication failed. Check that the API key is present, valid, and formatted correctly.
403— The key or user does not have permission for the requested action or entity. Check scopes, role permissions, and entity access.
404— The requested resource was not found, or your key does not have access to it. Check the ID and entity context.
409— The request conflicts with the current state of the resource. Refresh the resource and retry only if appropriate.
422— The request was understood but could not be processed. Review validation details, limits, or business-rule requirements.
429— Too many requests. Slow down, retry with backoff, and avoid tight polling loops.
500 or 503— A server or temporary availability issue occurred. Retry with exponential backoff and contact support if it persists.

Troubleshooting authentication errors

If you receive a 401 or 403 response:

Confirm the API key is included in the request using the expected authentication method.
Check that the key has not been revoked, rotated, or copied incorrectly.
Confirm the key has the scopes required for the endpoint.
Verify that the key or user has access to the relevant legal entity, account, card, transaction, or webhook endpoint.
Make sure you are calling the correct base URL and endpoint path.

Troubleshooting webhook errors

If webhook delivery is failing or events are not being processed:

Check endpoint availability. Your endpoint must be reachable over HTTPS and return a 2xx response quickly.
Check signature verification. Make sure you are verifying the raw request body exactly as received.
Check idempotency handling. Retried events may have the same event ID. Your system should handle duplicates safely.
Check endpoint status. If an endpoint was paused, disabled, or archived, it may not receive events until it is re-enabled or replaced.
Check logs. Log event IDs, event types, delivery timestamps, response status codes, and error messages so you can trace failures.

Need more help?

If you cannot resolve an API or webhook issue, contact Slash support through the in-app chat. Include the endpoint you called, the approximate time of the request, the HTTP status code, any request or event ID, and a short description of what you expected to happen.

Understanding Slash API Authentication, Webhooks, and Error Codes