Managing your organization using the Anaconda Cloud API#

Manually onboarding individual team members through the Anaconda Cloud graphical user interface (GUI) can be time consuming. For large teams, Anaconda recommends using API calls for a streamlined process.

The Anaconda Cloud API provides various calls to enable you to add users to an Anaconda Cloud organization and change their seat and token permissions. You must be an admin of an Anaconda Cloud organization with an active paid subscription to use these API calls.

Interacting with the API#

Anaconda maintains a Jupyter notebook that contains Python functions for interfacing with the API, along with some instructions for using the notebook itself:

Authenticating to the API#

The Anaconda Cloud API uses OAuth2 standard authentication (with an organization admin’s anaconda.cloud username and password) to generate a User_Token. A User_Token is required to create a service account.

Once a service account is created, use its credentials (the returned client_id and client_secret) for authentication in order to generate a ServiceAccount_Token to manage users via the other API calls described below.

Creating a service account#

Creating a service account allows an admin user to specify credentials for a specific machine or machines (like a build server or other machine for pipeline automation) and manage those machines in a similar capacity to a user. The service account can then allow the other API calls to be made directly to the organization the machine user is a part of.

You can create as many service accounts per organization as you need. However, Anaconda recommends limiting the number of service accounts to no more than is absolutely necessary. Restricting the number of service accounts enhances your organizations security posture.

Note

Service account names must be created using lower case letters, numbers, hyphens, or underscores, and cannot contain spaces or special characters.

API call#

# Replace <ORG_ID> with your organization ID, found in your Anaconda Cloud organization's URL: anaconda.cloud/organizations/<ORG_ID>/
POST /organizations/<ORG_ID>/service-accounts

Request

{
   "name":"<SERVICE_ACCOUNT_NAME>"
}

Request Example

{
   "name":"anaconda_cloud_org"
}

Response

{
   "name": "<SERVICE_ACCOUNT_NAME>",
   "client_id": "<GUID>",
   "org_id": "<GUID>",
   "client_secret": "<SECRET_ID>"
}

Response Example

{
   "name": "anaconda_cloud_org",
   "client_id": "1234abcd-1a2b-3c4d-5e6f-123456abcdef",
   "org_id": "abcd1234-1234-abcd-1a2b-3c4d5e6f7g8h",
   "client_secret": "1234567890abcdefghij_abcdefghij1234567_1a2b"
}

Get service account ID#

This call returns the ID of a previously created service account, but it will not reveal its secret.

API call#

# Replace <ORG_ID> with your organization ID, found in your Anaconda Cloud organization's URL: anaconda.cloud/organizations/<ORG_ID>/
GET organizations/<ORG_ID>/service-accounts

Response

{
   "name": "<SERVICE_ACCOUNT_NAME>",
   "client_id": "<GUID>",
   "org_id": "<GUID>",
}

Response Example

{
   "name": "anaconda_cloud_org",
   "client_id": "1234abcd-1a2b-3c4d-5e6f-123456abcdef",
   "org_id": "abcd1234-1234-abcd-1a2b-3c4d5e6f7g8h",
}

Deleting a service account#

This call deletes the service account associated with the supplied client_id.

API call#

# Replace <ORG_ID> with your organization ID, found in your Anaconda Cloud organization's URL: anaconda.cloud/organizations/<ORG_ID>/
# Replace <CLIENT_ID> with your client_id value
DELETE organizations/<ORG_ID>/service-accounts/<CLIENT_ID>

There’s no request or response information for this call. You will receive a 204 status code if the request is successful.

Automated Onboarding of new users#

If you are adding users to your organization that do not already have an anaconda.cloud account, you can use this call to initiate the automated onboarding process, which will add them to your organization, assign them a seat as a member, and issue them a token for access to the repository.

Admins will receive an email that the users have been added to the organization. Users will receive two emails, one welcoming them to the organization, and one containing their private access token, which allows them to use packages from anaconda.cloud.

Request

{
   "user_emails":"[<[email protected]>, <[email protected]>]"
}

Request Example

{
   "user_emails":"[[email protected], [email protected]]"
}

Response

{
   "users_in_onboarding_process": [
      "[email protected]" "[email protected]"
   ],
   "users_unavailable_for_onboarding": [],
   "total_organization_seats": "<TOTAL_SEATS>",
   "available_organization_seats": "<REMAINING_SEATS>"
}

Response Example

{
   "users_in_onboarding_process": [
      "[email protected]" "[email protected]"
   ],
   "users_unavailable_for_onboarding": [],
   "total_organization_seats": "1000",
   "available_organization_seats": "921"
}

Caution

If a user has an anaconda.cloud account associated with their email address, automated onboarding will fail.
If users listed under users_in_onboarding_process have started the onboarding process, any issues that occur during onboarding will not be reflected here. You will know there is an issue if a user did not get added to your organization.
If the number of available seats are less than the number of members you are attempting to add to your organization, users will be added until seats are no longer available, and the remaining users are shown in the users_unavailable_for_onboarding list.

Adding a user to your organization#

This call adds users to the organization.

If you do not provide an email address when making this call, the system creates an organization-managed user instead. Organization-managed users are not linked to individual accounts and are intended for programmatic use, allowing tokens to be generated specifically for automated processes or integrations.

You can create as many managed users as needed. However, Anaconda recommends limiting the number of managed users to only what is required. Restricting their use enhances the security posture of your organization.

Tip

When making requests to create organization-managed users, use the <FIRST_NAME> and <LAST_NAME> fields to provide a descriptive name for the token’s intended purpose. For example, if you are providing a token to a Jupyter Notebooks server, you might enter “Jupyter” and “Server-1” as a first and last name for the organization-managed user.

API call#

# Replace <ORG_ID> with your organization ID, found in your Anaconda Cloud organization's URL: anaconda.cloud/organizations/<ORG_ID>/
POST /organizations/<ORG_ID>/users

Request

{
   "email":"<EMAIL_ADDRESS>"
   "first_name": "<FIRST_NAME>",
   "last_name": "<LAST_NAME>"
}

Request Example

{
   "email":"[email protected]"
   "first_name": "Annie",
   "last_name": "Conda"
}

Response

{
   "first_name": "<FIRST_NAME>",
   "last_name": "<LAST_NAME>",
   "email": "<EMAIL_ADDRESS>",
   "id": "<GUID>"
}

Response example

{
   "first_name": "Annie",
   "last_name": "Conda",
   "email": "[email protected]",
   "id": "1a2b3c4d-1a2b-3c4d-5e6f-1a2b3c4d5f"
}

Note

If you do not provide a first and last name for your user, the API call will return null. The user can edit this information from their profile later, if necessary.

Assign seat to user#

This call assigns a seat to a given user for the organization the user is a member of.

API call#

# Replace <ORG_ID> with your organization ID, found in your Anaconda Cloud organization's URL: anaconda.cloud/organizations/<ORG_ID>/
# Replace <USER_ID> with the ID of the user you want to assign a seat
POST  /organizations/<ORG_ID>/users/<USER_ID>/seats

There’s no request or response information for this call. You will receive a 201 status code if the request is successful.

Assign token to user#

This call assigns a token to a given user. Tokens are a unique security key that enable users to access the subscription seat they have been assigned.

API call#

# Replace <ORG_ID> with your organization ID, found in your Anaconda Cloud organization's URL: anaconda.cloud/organizations/<ORG_ID>/
# Replace <USER_ID> with the ID of the user you want to assign a token
POST /organizations/<ORG_ID>/users/<USER_ID>/token

Request

{
   "expires_at": "<DATETIME>"
}

Request example

{
   "expires_at": "2022-07-29T00:00:00+00:00"
}

Response

{
   "token": "<TOKEN>",
   "expires_at": null
}

Response example

{
   "token": "1a2b34567c8d9101112e13f14g151617h18i19202122i23j",
   "expires_at": null
}

Syncing user tokens#

Renewing your subscription does not extend the lifespan of your token. If you have renewed your subscription and want to retain your current token, run this call to synchronize your token and extend its lifespan to your organization’s new subscription expiration date.

# Replace <ORG_ID> with your organization ID, found in your Anaconda Cloud organization's URL: anaconda.cloud/organizations/<ORG_ID>/
# Replace <USER_ID> with the ID of the user whose token needs to be synchronized
PATCH /organizations/<ORG_ID>/users/<USER_ID>/token

Revoking a users token#

This call revokes a token from a given user ID. It should be used when a user no longer needs access to their software subscription and can be used as the first part in a user removal process.

API call#

# Replace <ORG_ID> with your organization ID, found in your Anaconda Cloud organization's URL: anaconda.cloud/organizations/<ORG_ID>/
# Replace <USER_ID> with the ID of the user whose token you want to delete
DELETE /organizations/<ORG_ID>/users/<USER_ID>/token

Remove seat from user#

This call removes a subscription seat from a given user and can be used as the second part in a user removal process.

API call#

# Replace <ORG_ID> with your organization ID, found in your Anaconda Cloud organization's URL: anaconda.cloud/organizations/<ORG_ID>/
# Replace <USER_ID> with the ID of the user whose token you want to delete
DELETE /organizations/<ORG_ID>/users/<USER_ID>/seats

Remove user from organization#

This call removes a given user from a given organization and can be used as the final part in a user removal process.

API call#

# Replace <ORG_ID> with your organization ID, found in your Anaconda Cloud organization's URL: anaconda.cloud/organizations/<ORG_ID>/
# Replace <USER_ID> with the ID of the user whose token you want to delete
DELETE /organizations/<ORG_ID>/users/<USER_ID>