About

The Orgs API for Atlassian Cloud is a RESTful API that allows you to administer your organization’s managed accounts.

Before you start using the Orgs API, familiarize yourself with how the operations will affect the managed accounts in your organization.

To use the API, you must have a valid API key. The API key protects the API and ensures that you have permission to update, manage, enable, and disable the accounts owned by your organization.

Authentication and authorization

To use the Cloud Admin APIs you need an API key. This key gives full administrative access to your organization's directory so that you can create and update users or change group memberships. You use the API key as a bearer token in the Authorization header when making a REST API call. To create an API key:

  1. Go to admin.atlassian.com and click the name of your organization in the list.
  2. Click Settings, then click API keys.
  3. Click the Create API key button.
  4. Give your API key a name and choose an expiry date, then click Create.
  5. Copy the Organization ID and the API key to a safe place. Once you close the API key information screen, we won't show you this information again.
  6. When you are ready to close the page, click Done.

The default expiry date is set one week after the key is created. Once a key expires, you will need to create a new one. For more security or more convenience, you can set a shorter or longer expiry dateup to one year.

Version and URI

This documentation is for version 1 of the Orgs API. The URIs for resources have the following structure:

1
https://api.atlassian.com/admin/v1/orgs/<resource-name>

Pagination

The Orgs API uses pagination to conserve server resources and limit response size. If there are more results available after the current page, a next link is included in the JSON. You can use the cursor parameter to set a specific starting point for the results.

Orgs

Get orgs

GET /admin/v1/orgs

Returns a list of your orgs (based on your API key).

Request

Query parameters
cursor

string

Sets the starting point for the page of results to return.

page[cursor] Deprecated

string

This parameter has been deprecated and will be removed November 1, 2019. Use cursor instead.

Example

1
2
3
4
curl --request GET \
  --url 'https://api.atlassian.com/admin/v1/orgs' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Successful operation

Content typeValue
application/json

OrgPage

Get Org by ID

GET /admin/v1/orgs/{orgId}

Returns information about a single org by ID

Request

Path parameters
orgId Required

string

ID of the org to return

Example

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

Responses

Successful operation

Content typeValue
application/json

Org

Get users in an org

GET /admin/v1/orgs/{orgId}/users

Returns a list of users in an org.

Request

Path parameters
orgId Required

string

ID of the org to query

Query parameters
cursor

string

Sets the starting point for the page of results to return.

page[cursor] Deprecated

string

This parameter has been deprecated and will be removed November 1, 2019. Use cursor instead.

Example

1
2
3
4
curl --request GET \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/users' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Successful operation

Content typeValue
application/json

UserPage

Get domains in an org

GET /admin/v1/orgs/{orgId}/domains

Returns a list of domains in an org one page at a time.

Request

Path parameters
orgId Required

string

ID of the org to query

Query parameters
cursor

string

Sets the starting point for the page of results to return.

page[cursor] Deprecated

string

This parameter has been deprecated and will be removed November 1, 2019. Use cursor instead.

Example

1
2
3
4
curl --request GET \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/domains' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Successful operation

Content typeValue
application/json

DomainPage

Get domain by ID

GET /admin/v1/orgs/{orgId}/domains/{domainId}

Returns information about a single verified domain by ID.

Request

Path parameters
orgId Required

string

ID of the org the domain belongs to

domainId Required

string

ID of the domain to return

Example

1
2
3
4
curl --request GET \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/domains/{domainId}' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Successful operation

Content typeValue
application/json

Domain

Get an audit log of events from an org

GET /admin/v1/orgs/{orgId}/events

Returns an audit log of events from an org one page at a time.

Request

Path parameters
orgId Required

string

ID of the org

Query parameters
cursor

string

Sets the starting point for the page of results to return

q

string

Single query term for searching events.

from

string

The earliest date and time of the event represented as a UNIX epoch time.

to

string

The latest date and time of the event represented as a UNIX epoch time.

action

string

A query filter that returns events of a specific action type.

Example

1
2
3
4
curl --request GET \
  --url 'https://api.atlassian.com/admin/v1/orgs/{orgId}/events' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json'

Responses

Successful operation

Content typeValue
application/json

EventPage