Assign a team role via the external API

POST

/v1/team-access-grants

Adds the user identified by email to a team and assigns a built-in team role. The caller must also choose how project access is initialized.

teamRole accepts only admin, member, and guest. projectAccessMode accepts mapped (initialize access from existing projects in the team) and none (do not initialize project access). Existing active members, pending members, and owners are not overwritten.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Query Params

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Team access was granted or the existing grant was returned without being overwritten.

Bodyapplication/json

🟠401

🟠403

🟠422

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.apidog.com/v1/team-access-grants?locale=' \
--header 'X-Project-Id;' \
--header 'X-Client-Version;' \
--header 'X-Device-Id;' \
--header 'X-Branch-Id;' \
--header 'X-Apidog-Api-Version: 2024-03-28' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "teamId": 41,
    "email": "member@example.com",
    "teamRole": "admin",
    "projectAccessMode": "mapped"
}'

Response Example

200 - Example 1

{
    "success": true,
    "data": {
        "status": "granted",
        "teamId": 41,
        "email": "member@example.com",
        "userId": 101,
        "teamRole": "admin",
        "projectAccessMode": "mapped",
        "projectAccessCreatedCount": 3,
        "projectAccessUpdatedCount": 0,
        "projectAccessDeletedCount": 0,
        "teamRoleChanged": true,
        "projectAccessChanged": true
    }
}

Modified at 2026-08-18 09:25:31

Export Data in OpenAPI/Swagger Format

TeamRole