API Keys
Create and manage API keys for programmatic access to DevStride, audit and revoke every member's keys as an administrator, and know the rate limits and the API vocabulary changes.
On this page
An API key lets a script, an integration or the DevStride MCP server act in DevStride as the member who created it, with exactly that member's access. Keys are personal credentials, so they live under My Account → API Keys rather than in organization settings, but this page is the full reference for both members and administrators.
Create a key#
- Open My Account → API Keys and click New Key.
- Give it a Label you will recognize later (the tool or script that will use it) and choose the organization it is For. A key belongs to one organization.
- Copy the Api Secret now. It is shown once and cannot be retrieved again. Afterwards the table shows only the key's public identifier, label and organization.
From the table you can edit a key's label or delete it. Deleting revokes it immediately, so anything still using it needs a new key.
Treat keys like passwords
A key does whatever its owner can do. Store the secret somewhere safe, never paste it into shared chats or commit it to code, and delete any key you suspect has leaked.
What a key can do#
- A key inherits every permission its owner holds in that organization at the moment it is used. There are no per-key scopes and no expiry dates; revoking is the only way to narrow or end its access.
- A key stops working when its owner's membership in that organization ends, for example when the member is archived. You do not need to hunt down and revoke each key. Allow a few minutes for the change to take effect.
Permissions#
| To do this | You need |
|---|---|
| Create a key | Create API keys (CREATE_API_KEY), granted to every default role |
| Relabel or delete your own keys | Manage own API keys (MANAGE_OWN_API_KEYS), granted to every default role |
| See and revoke every member's keys | Manage all API keys (MANAGE_ALL_API_KEYS), Owner and Admin by default |
See Roles and Permissions for how these are assigned.
Audit and revoke keys across the organization#
A role with Manage all API keys sees an extra All Organization Api Keys table on the same page. It lists every member's keys with the owner's name, label and public identifier, so you can see what is in use and relabel or delete any of them, for example when someone leaves or a key appears in the wrong place. Secrets are never shown here; only the owner saw the secret, once, at creation.
Rate limits#
Each organization's API keys and MCP connections share one budget of 1,000 requests per minute. Requests over it are refused with HTTP 429 Too Many Requests, a Retry-After header giving the seconds until the minute resets, and a JSON body whose code is AUTH.ORGANIZATION_RATE_LIMIT_EXCEEDED and whose metadata carries limitPerMinute, retryAfterSeconds and windowResetsAt. Wait for the reset before retrying; a retry sooner is refused again. The DevStride MCP passes the wait on in its tool error, so an AI agent backs off by itself. Using DevStride in the browser never counts against the budget. If your integration needs more, contact support.
Vocabulary changes in the API and MCP tools#
The app has said Status and Workstream for a while; the API, the generated SDKs, the real-time events and the MCP tools now use the same words. The old names went through a compatibility window, and on November 7, 2026 they were retired. Integrators were told on November 1.
| Old name (retired) | New name |
|---|---|
lane — laneId, laneRank, laneCollectionId and other lane* keys and values |
status — statusId, statusRank, statusCollectionId |
folder — folderNumber and other folder* keys and values, folder-* real-time events |
workstream — the workstream* keys and values, workstream-* real-time events |
Since the retirement:
-
A request that sends an old name is refused with HTTP
400 Bad Request, before anything is changed. This covers body and query keys, values such as a sort field or an export column, and MCP tool arguments. The JSON body lists each old name it found and the one to send instead, so a failing script tells you exactly what to change:{ "code": "CONTRACT_RETIRED", "message": "This request uses names that have been removed: body.laneId (use statusId).", "retired": [{ "token": "body.laneId", "use": "statusId" }], "upgrade": { "docs": "https://api-docs.devstride.com" } } -
Responses carry only the new names. The duplicate old-named fields that used to sit beside the new ones (for example
folderCountandfoldersUpdated) are gone. -
The two
/foldersreads,GET /folders/{itemNumber}andPOST /folders/batch, answer HTTP410 Gonewith a body naming the/workstreamsreplacement. -
Real-time events are sent once, under the
workstream-*names. Thefolder-*events are no longer sent, so bind theworkstream-*names. -
Item exports take the column names
statusandstatusId;laneandlaneIdare refused.
Board folders in Plan Delivery are not part of this rename and keep their name.
Retired on October 10, 2026#
The old-name paths and MCP tools below were removed on October 10, 2026, after a week in which nobody called them. Each one has a status- or workstream-named replacement that behaves identically, and the retired paths no longer appear in the API reference.
Retired path (under /v1/organizations/{organizationId}) |
Use instead |
|---|---|
POST /lanes |
POST /statuses |
PATCH /lanes/{statusId}, DELETE /lanes/{statusId} |
PATCH /statuses/{statusId}, DELETE /statuses/{statusId} |
POST /lane-collections |
POST /status-collections |
PATCH /lane-collections/{statusCollectionId}, DELETE /lane-collections/{statusCollectionId} |
PATCH /status-collections/{statusCollectionId}, DELETE /status-collections/{statusCollectionId} |
GET /analytics/cumulative-lane-items |
GET /analytics/cumulative-status-items |
POST /folders |
POST /workstreams |
PATCH /folders/{itemNumber}, DELETE /folders/{itemNumber} |
PATCH /workstreams/{itemNumber}, DELETE /workstreams/{itemNumber} |
PATCH /folders/{itemNumber}/archive, PATCH /folders/{itemNumber}/unarchive |
PATCH /workstreams/{itemNumber}/archive, PATCH /workstreams/{itemNumber}/unarchive |
PATCH /folders/{itemNumber}/relationships |
PATCH /workstreams/{itemNumber}/relationships |
PATCH /folders/archive |
PATCH /workstreams/archive |
A call to a retired /lanes, /lane-collections or analytics path is still checked for your key and access as before, then answered with HTTP 410 Gone and a JSON body that names the replacement, so a failing script tells you exactly what to change:
{
"code": "CONTRACT_RETIRED",
"message": "POST /v1/organizations/{organizationId}/lanes (createLaneDeprecated) has been removed. Use POST /v1/organizations/{organizationId}/statuses (createStatus).",
"upgrade": {
"operationId": "createStatus",
"method": "POST",
"path": "/v1/organizations/{organizationId}/statuses",
"docs": "https://api-docs.devstride.com"
}
}
The seven retired /folders write paths were removed altogether on October 31, 2026, after a further week in which nobody called them. They now answer a plain HTTP 404 Not Found that names no replacement; use the /workstreams paths in the table. The two /folders reads were retired on November 7, 2026, as described under Vocabulary changes.
The MCP server no longer offers create_lane, update_lane, delete_lane, create_lane_collection, update_lane_collection, delete_lane_collection, create_folder, update_folder, delete_folder, archive_folder or unarchive_folder. Use the matching *_status, *_status_collection and *_workstream tools, which do the same job. rank_item no longer accepts the scope lane; use status.
Stored settings use the new words#
What DevStride stores uses the new names, and settings saved before the change have been converted, so anything that reads these values back sees the new spelling. Send the new spelling when you write them; the old one is refused like any other retired name.
- Automations: condition paths read
statusId(for example$.statusId), a change-status action storesstatusId, and the Service Desk action that follows a customer status stores the value typeservice-desk-status(formerlyservice-desk-lane). Workstream triggers and actions use theworkstreamnames. - Automation messages and formulas: the status variable is
itemStatus.createWorkflowandupdateWorkflowrefuse a condition or action that still names an old status reference, or a template that usesitemLane, with theCONTRACT_RETIREDbody shown above;GETorganization no longer listsvariables.itemLane. A calculated field's formula that uses${itemLane}is refused the same way, unless your organization has a custom field named Lane. - Notification preferences: the status-change preference is
statusModified;laneModifiedis refused. - Saved views: a view's
datais stored as version 2, which uses the new names (for examplefilters.statusId). A version-1 body in the new names is accepted, stored as version 2 and returned as version 2. A save that still names an old status spelling (a filter key, an advanced-filter rule field, a sort, a view mode or an axis) is refused with theCONTRACT_RETIREDbody, naming the spelling to send; workstream filter keys are still converted for you. - SLA policies: an update accepts
filterSchemaVersion1or2; SLA reports filter bystatusId. - Jira and Azure DevOps project links: use
statusCollectionIdandstatusMappings;laneCollectionIdandlaneMappingsare refused.
History, notifications and activity use the new words#
Since November 11, 2026, item history, notifications and the activity log say status too (automation runs and import records since November 12), including the records written before the change, which were converted once. Reads return only the new values, and a filter that sends an old one is refused with HTTP 400 and the CONTRACT_RETIRED body shown above.
- Notifications (
findNotifications): a status change has the actionstatus_modified. Filtering bylane_modifiedis refused. - Item history (
getItemTransactions): status moves areadded_to_statusandremoved_from_status. The trending reports (getTrendingItems,getTrendingItemCounts) refuseadded_to_laneandremoved_from_laneintransactionTypes. - Activity log (
findActivityLogs): entries carrystatusId,statusRankandrootWorkstreamNumber, older entries included;laneId,laneRankandrootFolderNumberno longer appear. - Automation runs: a run record lists the item's status once, under the new names, older runs included;
lane,laneId,laneRank,hasExplicitClosedLane,laneChangedAtandrootFolderno longer appear. - Import jobs and runs: the entity values are
StatusEntity,StatusCollectionEntityandWorkstreamEntity, older imports included. An old import whose converted file has been removed cannot be run again; upload the file again to import it. - Exports: column headings and values read Added To Status and Removed From Status, and the item-cycle export's transaction-type column is filled in again.
The MCP tools that read these records return the same new values. The read-only database stores them too.
The value workstream for an item type#
Wherever an item type or a relationship entity used to take folder, send and read workstream. Responses return workstream without any opt-in; ?contract=workstream-v2 is still accepted and changes nothing. A request pinned with ?contract=workstream-v1 is refused with HTTP 400, naming workstream-v2.
Links to a workstream open the map with ?selectedWorkstream=. Links in older messages that use ?selectedFolder= still open the map, but no longer select the workstream: change them to ?selectedWorkstream=.
Saved views: avoid overwriting a newer version#
Every saved view carries a dataVersion that moves forward each time its data is saved. When you update a view's data, send the dataVersion you last read as expectedDataVersion. If the view has been saved since, the update is refused with HTTP 409 instead of overwriting the newer version; read the view again, re-apply your change and retry. Leave expectedDataVersion out to save without the check.
Saved views: which options are stored#
When you create a saved view or update its data, DevStride stores only the options that the view's screen (its location) defines. An option the screen does not define, for example one it has since retired, is left out without an error, so sending back what you read keeps working. An option the screen does define must hold a value of the right kind, such as true or false for an on/off option: otherwise the request is refused with HTTP 400 Bad Request, naming the option, and nothing is saved. The request and response shapes are unchanged. Time Allocation Matrix views keep their own check, which refuses an option it does not know.
Related#
- Setting Up Your Connection — connect an AI client with a key or OAuth.
- Connected Apps — revoke OAuth grants, the other way tools act as you.
- Connect AI and MCP
- API reference