pages/account/organizations/organization-admin-api.txt

route: /docs/account/organizations/organization-admin-api
title: Organization API
description: Manage organization membership, linked teams, and groups programmatically with the Organization API.

Organization API
The Organization API lets you perform actions that apply across teams linked to an organization, such as moving users between those teams, reporting on pooled usage across teams, and managing organization groups. It uses an Organization API key and the same HTTP patterns as the team Admin API.
The Organization API uses Basic Authentication with your API key as the username.
For details on creating API keys, authentication methods, rate limits, and best practices, see the API Overview.
Organization API keys vs Team API keys
Organization API keys are organization-scoped credentials. Team API keys are team-scoped credentials.
Use an Organization API key when calling organization-level endpoints like /organizations/team-memberships/sync, /organizations/pooled-usage, and /organizations/groups.
Use a Team API key when calling team-level endpoints under /teams/* (for example, /teams/members and /teams/spend).
Key differences
Scope: Organization API keys can act across teams linked to the same organization. Team API keys can only act within one team.
Endpoint compatibility: Organization endpoints require Organization API keys. Team endpoints require Team API keys.
Key scopes: Each route requires a specific scope on the key. Membership and group routes need members:*; usage routes need usage:*. Keys with admin:* work everywhere because admin implies the other scopes.
Authorization failures: If the key scope does not match the endpoint scope, requests fail with authentication or authorization errors (typically 401 or 403).
How should I pass an Organization API key?
Pass it the same way as other Cursor API keys: Basic authentication with the key as the username and an empty password.
curl -X POST https://api.cursor.com/organizations/team-memberships/sync \
-u YOUR_ORGANIZATION_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"organizationId": "org_abc123",
"users": [
{ "userId": 12345, "destinationTeamId": 7 }
]
}'
Endpoints
Sync Organization Team Memberships
POST/organizations/team-memberships/sync
Move one or more users between teams that are linked to your organization. For each requested move, the member’s team assignment within the organization is set to exactly the destination team, and they are removed from any other linked teams. This matches the bulk style of the CSV import API: you send an array of users and receive a result row for each one.
Request body
organizationId string Required
Public organization ID (for example org_abc123). Must match the organization for the Organization API key used to call the endpoint.
users array Required
Non-empty list of moves (at most 500 per request). Each element is an object with:
userId number | string: ID of the user to move. Accepts either an integer numeric ID (for example 12345) or a string ID (for example "user_abc123").
destinationTeamId number: Integer team ID for the destination. Must be a team linked to the organization.
Success response (HTTP 200)
results array
One entry per requested move, in order. Each object includes userId, destinationTeamId, and either status: "success" or status: "error" with errorMessage when that row failed.
successCount number
Number of rows with status: "success".
errorCount number
Number of rows with status: "error".
Availability: Enterprise only
Authentication: Organization API key (Basic auth). The key must include the members:* scope for this route; keys with admin:* also work because admin implies members.
Organization match: The organizationId in the body must be the same organization as the API key; otherwise the request is rejected.
The target user must already be a member of the organization for a move to succeed.
The destination team must be linked to the organization for a move to succeed.
If one move in users fails, others can still succeed; check each results entry’s status and errorMessage.
Batch size: A single request may include up to 500 moves. Send additional batches in separate requests if needed.
curl -X POST https://api.cursor.com/organizations/team-memberships/sync \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"organizationId": "org_abc123",
"users": [
{ "userId": 12345, "destinationTeamId": 7 },
{ "userId": "user_abc123", "destinationTeamId": 8 }
]
}'
Response:
{
"results": [
{
"userId": 12345,
"destinationTeamId": 7,
"status": "success"
},
{
"userId": "user_abc123",
"destinationTeamId": 8,
"status": "success"
}
],
"successCount": 2,
"errorCount": 0
}
Error responses:
Most thrown API errors use HTTP 401, 403, or 400 and a JSON body shaped like:
{
"code": "error",
"message": "…"
}
404: organization not found (this route uses a different field name for the message):
{
"error": "Organization not found"
}
401: invalid Organization API key (wrong or missing key):
{
"code": "error",
"message": "Invalid Organization API Key"
}
401: missing required scope (key is valid but does not include members:* or admin:*):
{
"code": "error",
"message": "Organization API key missing required scope: members:*"
}
403: organization does not match the key (organizationId in the body is not the organization for this API key):
{
"code": "error",
"message": "Not authorized"
}
400: invalid request body (examples; only one applies per failed request):
{
"code": "error",
"message": "Request body is required"
}
{
"code": "error",
"message": "organizationId is required"
}
{
"code": "error",
"message": "users must be a non-empty array"
}
{
"code": "error",
"message": "users must not contain more than 500 moves"
}
Per-row failures (HTTP 200): Validation or business rules for a single move are returned in results with status: "error" and errorMessage. Invalid userId / destinationTeamId types use 0 for the invalid field in the row:
{
"results": [
{
"userId": 0,
"destinationTeamId": 7,
"status": "error",
"errorMessage": "Invalid userId"
}
],
"successCount": 0,
"errorCount": 1
}
{
"results": [
{
"userId": 12345,
"destinationTeamId": 0,
"status": "error",
"errorMessage": "Invalid destinationTeamId"
}
],
"successCount": 0,
"errorCount": 1
}
{
"results": [
{
"userId": 0,
"destinationTeamId": 0,
"status": "error",
"errorMessage": "Invalid userId. Invalid destinationTeamId"
}
],
"successCount": 0,
"errorCount": 1
}
Per-row failures (HTTP 200): From the move logic when inputs are well-typed but the move cannot be applied:
{
"results": [
{
"userId": 12345,
"destinationTeamId": 999,
"status": "error",
"errorMessage": "Team is not linked to this organization"
}
],
"successCount": 0,
"errorCount": 1
}
{
"results": [
{
"userId": 12345,
"destinationTeamId": 7,
"status": "error",
"errorMessage": "User is not a member of this organization"
}
],
"successCount": 0,
"errorCount": 1
}
{
"results": [
{
"userId": 12345,
"destinationTeamId": 7,
"status": "error",
"errorMessage": "User not found"
}
],
"successCount": 0,
"errorCount": 1
}
Usage
Report on usage across every team linked to your organization. These endpoints aggregate data from all teams in the organization pool, so you don't need a separate Team API key per team. For single-team reporting, use the team Admin API usage endpoints instead.
Availability: Enterprise only
Authentication: Organization API key (Basic auth). The key must include the usage:* scope for these routes; keys with admin:* also work because admin implies usage.
Organization match: The organizationId in the body must be the same organization as the API key; otherwise the request is rejected.
Team containment: Any teamId (or entry in teamIds) must belong to the organization. Requests that reference a team outside the organization are rejected.
Polling: Usage data is aggregated at the hourly level. Poll these endpoints at most once per hour. Rate limited to 20 requests per minute. See rate limits and best pra
…