Skip to main content

​
Overview

Aptly uses per-board API keys to authenticate REST API requests. Each board generates its own unique key, which is passed as an x-token header on every request.

​
Finding your API key and POST URL

  1. Open the board you want to connect to
  2. Click Card Sources in the board toolbar
  3. Select API
  4. Toggle the switch to enable the REST API
  5. Copy your API Key and POST URL
The POST URL already contains your board ID and is the endpoint you will send requests to. Your API key authenticates those requests.
Treat your API key like a password. Do not commit it to source control or expose it in client-side code. If a key is compromised, click Regenerate to invalidate it and issue a new one.

​
Making an authenticated request

Pass your API key as the x-token header on every request: 
curl -X POST "https://api.getaptly.com/api/aptlet/YOUR_BOARD_ID" \
  -H "x-token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Name": "John Smith", "Status": "New"}'

​
Card Sources settings

When you enable the API on a board, you can configure the following options: Update Mode Controls what happens when a request includes an _id field matching an existing card.
  • Always Create New — ignores _id and always inserts a new card
  • Update if exists — updates the matching card if found, otherwise creates a new one
Create Fields When enabled, any keys in the request payload that do not match existing board fields will automatically create new fields on the board. Disable this if you want strict field validation. Webhook URL An endpoint on your server that Aptly will POST to when cards on this board are created or updated. See Webhooks below. Webhook Signing Key A secret key used to verify that webhook payloads were sent by Aptly. Include this in your webhook handler to validate incoming requests.

​
Webhooks

If you provide a Webhook URL, Aptly will send a POST request to that URL whenever a card on the board is created or updated. The payload contains the full card data. To verify a webhook request is genuinely from Aptly, use the Webhook Signing Key shown in the Card Sources panel. Validate the request signature in your server before processing the payload.
If your Webhook Signing Key is ever exposed, return to Card Sources and regenerate it immediately.