Add users to authentication policy

Overview

An authentication policy allows you to specify authentication settings for different sets of users and configurations in your organization. It verifies that users who access your Atlassian organization are who they claim to be.

This guide will walk you through the usage of the API to add users in an authentication policy and troubleshoot.

Explore authentication policies

Add users to a policy

POST /admin/control/v1/orgs/{orgId}/auth-policy/{policyId}/add-users

This will add a list of users to an existing authentication policy. Just make sure to use their email addresses when adding them.

Request

1
2
curl --location 'https://api.atlassian.com/admin/control/v1/orgs/96c9b91d-3eab-41b4-9d9c-09eb84db70cf/auth-policy/90781be9-0863-45f0-92b9-1612379ffa5c/add-users' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data-raw '{
    "users": [
        "user1@domain.com",
        "user2@domain.com"
    ]
}'

Response

This is an asynchronous API. The response to this call will return a taskId. By making a request to the Get the status of a task API, you can check the status of the add users in policy operation.

1
2
{
"taskId":"358d916a-aed3-474a-9ae0-17def3bad866",
"taskLink":"https://api.atlassian.com/admin/control/v1/orgs/96c9b91d-3eab-41b4-9d9c-09eb84db70cf/auth-policy/task/358d916a-aed3-474a-9ae0-17def3bad866"
}

Get the status of a task

GET /admin/control/v1/orgs/{orgId}/auth-policy/task/{taskId}

Verifies that users are assigned to the intended policy and report errors, if any.

Request

1
2
curl --request GET \
   --url 'https://api.atlassian.com/admin/control/v1/orgs/{orgId}/auth-policy/task/{taskId}' \
   --header 'Authorization: Bearer <access_token>' \
   --header 'Accept: application/json'

Response

1
2
{
    "inProgressCount": 0,
    "successCount": 2,
    "failureCount": 0,
    "failureReasons": []
}

In this case we can see that the operation to add users in a policy was a success. 2 users were successfully moved, there are no in progress users and there are no errors.

Adding users with incorrect email addresses

If an invalid email is included in the request body, only the invalid user will fail. The remaining valid users will successfully be added in the desired policy. To see the reason for failure, we make a request to the Get the status of a task API returned.

Request

1
2
curl --location 'https://api.atlassian.com/admin/control/v1/orgs/96c9b91d-3eab-41b4-9d9c-09eb84db70cf/auth-policy/90781be9-0863-45f0-92b9-1612379ffa5c/add-users' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
  --data-raw '{
    "users": [
        "validUser@domain.com",
        "doesNotExist@domain.com"
    ]
}'

Response from task status API

All users, except those with incorrect email addresses, will move to the intended policy. For those with errors, a 404 user not found error message will be shown.

1
2
{
    "inProgressCount": 0,
    "successCount": 1,
    "failureCount": 1,
    "failureReasons": [
        {
            "emails": [
                "doesNotExist@domain.com"
            ],
            "details": {
                "status": 404,
                "title": "User not found",
                "detail": "User not found."
            }
        }
    ]
}

Troubleshooting errors

When transferring users with incorrect information, here are some scenarios you might encounter:

• Moving users in a policy that doesn't exist
• Moving users in a deleted policy
• Moving a user that is not a managed account in a policy
• Moving selectively unclaimed users in a policy
• Moving users synced with the SCIM protocol to a non-billable policy

In each of these situations, you'll see the corresponding error. For any failures present, the Get the status of a task API will return the list of failed users and the reason why the operation failed.

Currently, moving a max of 500 users per API request is supported. For moving more than 500 users into a policy, please make multiple API requests. Organizations can make up to 10 calls per minute to this API.