diff --git a/docs/dev/api.md b/docs/dev/api.md index 3f6bc91a3e..3b28f5a173 100644 --- a/docs/dev/api.md +++ b/docs/dev/api.md @@ -17,7 +17,8 @@ You can check the current accessibility of any Sauce Labs system on the [Sauce L ## What You'll Need - A Sauce Labs account ([Log in](https://accounts.saucelabs.com/am/XUI/#login/) or sign up for a [free trial license](https://saucelabs.com/sign-up)) -- Your Sauce Labs [Username and Access Key](https://app.saucelabs.com/user-settings) +- [Username and access key](https://app.saucelabs.com/user-settings) of your Sauce Labs user account. + - Alternatively, you can use the credentials of a [service account](/basics/acct-team-mgmt/managing-service-accounts). The username and access key for a service account are provided during [its creation](/basics/acct-team-mgmt/managing-service-accounts/#creating-a-service-account). ## Accessing the APIs @@ -39,6 +40,8 @@ The request examples throughout the API documentation utilize variables in place The Sauce Labs API uses API keys to authenticate requests. You can view and manage your API key under your [Sauce Labs User Settings](https://app.saucelabs.com/user-settings). +Alternatively, you can use the username and access key of a [service account](/basics/acct-team-mgmt/managing-service-accounts) to authenticate API requests. Service account credentials are generated during [account creation](/basics/acct-team-mgmt/managing-service-accounts/#creating-a-service-account). + Authentication to the API is performed via [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). Provide your username and API key as the basic auth username and password values, respectively. All requests must be made over HTTPS. Calls made over HTTP or without proper authentication will fail. You can provide your authentication credentials as inline parameters of your request or using a Basic Header. @@ -115,7 +118,7 @@ The Sauce Labs REST API places rate limits on some endpoints in order to prevent For example: -- Incoming authenticated API requests have rate limits imposed against the individual user accounts. +- Incoming authenticated API requests have rate limits imposed against the individual account. - Incoming unauthenticated API requests have rate limits imposed against the IP addresses. Requests received after the rate limit is reached return a [429 response code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429#:~:text=The%20HTTP%20429%20Too%20Many,before%20making%20a%20new%20request) indicating that the number of allowable requests has been exceeded. diff --git a/docs/dev/api/accounts.md b/docs/dev/api/accounts.md index 783f4ad0a4..ff2c767814 100644 --- a/docs/dev/api/accounts.md +++ b/docs/dev/api/accounts.md @@ -2650,3 +2650,569 @@ curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ ``` + +--- + +## Service account + +### Lookup Service Accounts + +
+GET /team-management/v1/service-accounts/ +

+ +Lists existing service accounts in your organization. You can filter the results using the query parameters below. + +#### Parameters + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
id

| QUERY | OPTIONAL | STRING |

Comma-separated service account IDs.

username

| QUERY | OPTIONAL | STRING |

Substring username search phrase.

teams

| QUERY | OPTIONAL | STRING |

Comma-separated team IDs.

limit

| QUERY | OPTIONAL | INTEGER |

Number of results to return per page.

offset

| QUERY | OPTIONAL | INTEGER |

The initial index from which to return the results.

+ + + + + +```jsx title="Sample Request" +curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ +--request GET 'https://api.us-west-1.saucelabs.com/team-management/v1/service-accounts/?limit=100&offset=0' | json_pp +``` + +```jsx title="Sample Request with Filters" +curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ +--request GET 'https://api.us-west-1.saucelabs.com/team-management/v1/service-accounts/?id=7ddb81628f5f4e77b5f74d9dec4980db,8ec1b3d47a5e4f25a7b6c8e9f0123456&username=bot-automation&teams=bd8466c7c94f4f2a8641a1fd4ac1a89d,c7a2b3d4e5f67890abcdef1234567890&limit=10&offset=0' | json_pp +``` + + + + +```jsx title="Sample Request" +curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ +--request GET 'https://api.eu-central-1.saucelabs.com/team-management/v1/service-accounts/?limit=100&offset=0' | json_pp +``` + +```jsx title="Sample Request with Filters" +curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ +--request GET 'https://api.eu-central-1.saucelabs.com/team-management/v1/service-accounts/?id=7ddb81628f5f4e77b5f74d9dec4980db,8ec1b3d47a5e4f25a7b6c8e9f0123456&username=bot-automation&teams=bd8466c7c94f4f2a8641a1fd4ac1a89d,c7a2b3d4e5f67890abcdef1234567890&limit=10&offset=0' | json_pp +``` + + + + +#### Responses + + + + + + + + + + + + + +
200Success. Service account list returned.
403Forbidden. You do not have permission to look up service accounts.
+ +```jsx title="Sample Response" +{ + "count": 2, + "links": { + "first": "https://api.us-west-1.saucelabs.com/team-management/v1/service-accounts/?limit=10&offset=0", + "last": "https://api.us-west-1.saucelabs.com/team-management/v1/service-accounts/?limit=10&offset=0", + "next": null, + "previous": null + }, + "results": [ + { + "id": "7ddb81628f5f4e77b5f74d9dec4980db", + "username": "bot-automation-service-account-d2164", + "name": "Automation Service Account", + "team": { + "id": "bd8466c7c94f4f2a8641a1fd4ac1a89d", + "name": "QA Automation Team" + }, + "creator": { + "id": "504e6c7223fd4159815a08c38f677701", + "username": "john.doe", + "email": "john.doe@example.com" + } + }, + { + "id": "8ec1b3d47a5e4f25a7b6c8e9f0123456", + "username": "bot-automation-service-account-565ad", + "name": "Staging Automation Account", + "team": { + "id": "c7a2b3d4e5f67890abcdef1234567890", + "name": "Staging Team" + }, + "creator": { + "id": "e1f2g3h4i5j6k7l8m9n0o1p2q3r4s5t6", + "username": "jane.doe", + "email": "jane.doe@example.com" + } + } + ] +} +``` + +

+ +--- + +### Get a Specific Service Account + +
+GET /team-management/v1/service-accounts/{uuid}/ +

+ +Retrieves details of the specified service account. + +#### Parameters + + + + + + + + +
uuid

| PATH | REQUIRED | STRING |

The unique identifier of the service account. You can find the uuid in the URL of the [service account details view](/basics/acct-team-mgmt/managing-service-accounts/#accessing-the-service-account-details-view) in the Sauce Labs UI. You can also look up the uuid using the [Lookup Service Accounts](#lookup-service-accounts) endpoint.

+ + + + + +```jsx title="Sample Request" +curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ +--request GET 'https://api.us-west-1.saucelabs.com/team-management/v1/service-accounts/' | json_pp +``` + + + + +```jsx title="Sample Request" +curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ +--request GET 'https://api.eu-central-1.saucelabs.com/team-management/v1/service-accounts/' | json_pp +``` + + + + +#### Responses + + + + + + + + + + + + + + + + + + + + +
200Success. Service account details returned.
403Forbidden. You do not have permission to access this resource.
404Not found. The specified service account does not exist.
+ +```jsx title="Sample Response" +{ + "id": "7ddb81628f5f4e77b5f74d9dec4980db", + "username": "bot-automation-service-account-d2164", + "name": "Automation Service Account", + "created_at": "2024-10-24T14:45:43.606414Z", + "updated_at": "2025-01-23T15:57:32.520638Z", + "last_activity_time": "2025-02-15T11:22:10.123456Z", + "creator": { + "id": "504e6c7223fd4159815a08c38f677701", + "username": "john.doe", + "email": "john.doe@example.com" + }, + "team": { + "id": "bd8466c7c94f4f2a8641a1fd4ac1a89d", + "name": "QA Automation Team" + } +} +``` + +

+ +--- + +### Create a Service Account + +
+POST /team-management/v1/service-accounts/ +

+ +Creates a new service account. Provide the required fields to generate a service account with an automatically generated username and access key. + +#### Parameters + + + + + + + + + + + + +
name

| BODY | REQUIRED | STRING |

A user-friendly display name for the service account. Must be between 1 and 128 characters.

team_uuid

| BODY | REQUIRED | STRING |

The unique identifier of the team to which the service account will be assigned. You can look up team IDs using the [Lookup Teams](#lookup-teams) endpoint.
Note: Team admins can only create accounts in their [active team](/basics/acct-team-mgmt/switching-active-team/).

+ + + + + +```jsx title="Sample Request" +curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ +--request POST 'https://api.us-west-1.saucelabs.com/team-management/v1/service-accounts/' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "name": "Team A bot", + "team_uuid": "bd8466c7c94f4f2a8641a1fd4ac1a89d" +}' | json_pp +``` + + + + +```jsx title="Sample Request" +curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ +--request POST 'https://api.eu-central-1.saucelabs.com/team-management/v1/service-accounts/' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "name": "Team A bot", + "team_uuid": "bd8466c7c94f4f2a8641a1fd4ac1a89d" +}' | json_pp +``` + + + + +#### Responses + + + + + + + + + + + + +
201Success. Service account created successfully.
403Forbidden. You do not have permission to create a service account.
+ +```jsx title="Sample Response" +{ + "id": "7ddb81628f5f4e77b5f74d9dec4980db", + "access_key": "8e27aba8-be73-4ef3-9c2b-20f796b5ebff", + "username": "bot-automation-service-account-d2164" +} +``` + +

+ +--- + +### Update a Service Account + +
+PATCH /team-management/v1/service-accounts/{uuid}/ +

+ +Updates the details of an existing service account. You can only update the **name** field, which is a user-friendly, editable display name. The username remains immutable. + +#### Parameters + + + + + + + + + + + + + + +
uuid +

| PATH | REQUIRED | STRING |

+

The unique identifier of the service account. You can find the uuid in the URL of the [service account details view](/basics/acct-team-mgmt/managing-service-accounts/#accessing-the-service-account-details-view) in the Sauce Labs UI. You can also look up the uuid using the [Lookup Service Accounts](#lookup-service-accounts) endpoint.

+
name

| BODY | REQUIRED | STRING |

A user-friendly display name for the service account. Must be between 1 and 128 characters.

+ + + + + +```jsx title="Sample Request" +curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ +--request PATCH 'https://api.us-west-1.saucelabs.com/team-management/v1/service-accounts/' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "name": "Bot Foo Bar" +}' | json_pp +``` + + + + +```jsx title="Sample Request" +curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ +--request PATCH 'https://api.eu-central-1.saucelabs.com/team-management/v1/service-accounts/' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "name": "Bot Foo Bar" +}' | json_pp +``` + + + + +#### Responses + + + + + + + + + + + + + + + + +
200Success. Service account updated successfully.
403Forbidden. You do not have permission to update this service account.
404Not found. The specified service account does not exist.
+ +```jsx title="Sample Response" +{ + "id": "7ddb81628f5f4e77b5f74d9dec4980db", + "username": "bot-automation-service-account-d2164", + "name": "Bot Foo Bar", +} +``` + +

+ +--- + +### Delete a Service Account + +
+DELETE /team-management/v1/service-accounts/{uuid}/ +

+ +Deletes the specified service account from your organization. + +#### Parameters + + + + + + + + +
uuid +

| PATH | REQUIRED | STRING |

+

The unique identifier of the service account. You can find the uuid in the URL of the [service account details view](/basics/acct-team-mgmt/managing-service-accounts/#accessing-the-service-account-details-view) in the Sauce Labs UI. You can also look up the uuid using the [Lookup Service Accounts](#lookup-service-accounts) endpoint.

+
+ + + + + +```jsx title="Sample Request" +curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ +--request DELETE 'https://api.us-west-1.saucelabs.com/team-management/v1/service-accounts/' +``` + + + + +```jsx title="Sample Request" +curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ +--request DELETE 'https://api.eu-central-1.saucelabs.com/team-management/v1/service-accounts/' +``` + + + + +#### Responses + + + + + + + + + + + + + + + + +
204Success. Service account deleted successfully. No content returned.
403Forbidden. You do not have permission to delete this service account.
404Not found. The specified service account does not exist.
+ +

+ +--- + +### Reset Service Account Access Key + +
+POST /team-management/v1/service-accounts/{uuid}/reset-access-key/ +

+ +Resets the access key for the specified service account. A new access key is generated and returned in the response. + +:::warning +Regenerating an access key invalidates the previous key. Any tests or configurations using the previous key will fail, so make sure to update all tests and credential environment variables with the new key. +::: + +#### Parameters + + + + + + + + +
uuid +

| PATH | REQUIRED | STRING |

+

The unique identifier of the service account. You can find the uuid in the URL of the [service account details view](/basics/acct-team-mgmt/managing-service-accounts/#accessing-the-service-account-details-view) in the Sauce Labs UI. You can also look up the uuid using the [Lookup Service Accounts](#lookup-service-accounts) endpoint.

+
+ + + + + +```jsx title="Sample Request" +curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ +--request POST 'https://api.us-west-1.saucelabs.com/team-management/v1/service-accounts//reset-access-key/' | json_pp +``` + + + + +```jsx title="Sample Request" +curl -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \ +--request POST 'https://api.eu-central-1.saucelabs.com/team-management/v1/service-accounts//reset-access-key/' | json_pp +``` + + + + +#### Responses + + + + + + + + + + + + + + + + +
200Success. Service account access key was rotated.
403Forbidden. You do not have permission to reset the access key for this service account.
404Not found. The specified service account does not exist.
+ +```jsx title="Sample Response" +{ + "access_key": "3f78c473-3396-432d-b6d1-48e2dd7c57b1" +} +``` + +