Introduction to the Advanced Server Access API

Authentication

Most calls to the Advanced Server Access (ASA) API require an HTTP Authorization header with a value of Bearer {AUTH_TOKEN}.

To retrieve an auth token, you need to create a Service User and API key, then pass the API key information to the Issue a Service User token endpoint.

Auth tokens may expire at any time, so code that uses them should be prepared to handle a 401 Unauthorized response code by creating a new auth token.

Permissions

The permissions of an ASA User are determined by their ASA Group memberships.

Each ASA Group that an ASA User is a member of can imply permissions through Team-wide Roles and Project membership.

Team-wide Roles

Each ASA Group can have Team-wide Roles affiliated with it. For example, you might create an Administrators Group that grants the access_admin Role to individuals who can make configuration changes.

An ASA User's permissions are equivalent to the most permissive Role that they are granted.

Available Team Roles

Pagination

Requests that return lists of objects may support pagination. By default pagination limits the number of returned objects in a given response to 100.

ASA provides information about pagination in Link headers:

• A Link header that contains rel="next" indicates that a subsequent page is available and contains the URL that should be used to fetch it.
• A Link header that contains rel="prev" indicates that a previous page is available and contains the URL that should be used to fetch it.

To fetch a full list of resources, Clients should use the following approach when retrieving lists:

1. Perform the desired list call without providing any pagination-related parameters.
2. Process the response body by referencing objects in the body field called list .
3. Check for a Link header value with rel="next" . If such a value exists, fetch it and repeat steps two and three.

An example of a paginated request that contains the URL from the rel="next" Link header:

curl -v -X GET \
-H "Authorization: Bearer {jwt}" \
https://app.scaleft.com/v1/teams/{team_name}/projects?offset={next_page_offset}

Clients that want to fetch pages of less than 100 items (for testing pagination, for example) may pass a count parameter to the initial list call. This parameter is automatically propagated to each of the pagination Link URLs that are contained in the response, so that it is only necessary to provide the parameter to the initial call.

List responses that don't currently implement pagination limits may begin to do so without warning in the future. As a result, it is recommended that Clients implement pagination when calling any list method, so that they automatically continue working if pagination is implemented.

An example of a paginated response body that contains a list field:

{
  "list": [
    {
      "id": "5dfc51da-3991-4330-88bf-ef710a7d53e5",
      "name": "everyone",
      "roles": [
        "access_admin",
        "access_user"
      ],
      "federated_from_team": null,
      "federation_approved_at": null,
      "deleted_at": null
    },
    {
      "id": "ad2ff761-83da-4769-b86c-85042eefc1d7",
      "name": "owners",
      "roles": [
        "access_admin",
        "access_user"
      ],
      "federated_from_team": null,
      "federation_approved_at": null,
      "deleted_at": null
    }
  ]
}

Rate limiting

Rate limits control access to Advanced Server Access APIs by measuring the rate at which users send requests during a rate limit period. After exceeding this limit, users must wait for requests to replenish before submitting again.

Every API response includes headers related to rate limiting:

• X-RateLimit-Limit - Describes the total number of operations permitted per rate limit period.
• X-RateLimit-Remaining - Describes the total number of remaining operations permitted during the current rate limit period.
• X-RateLimit-Reset - Contains a unix timestamp indicating when the number of rate limit requests fully replenishes.
• X-RateLimit-Retry-At - Sent after exceeding the rate limit and contains a unix timestamp indicating when the number of rate limit requests partially replenishes. If multiple requests share the same timestamp, sending them at the same time may cause additional rate limiting.

Requests that exceed a rate limit receive an HTTP 429 - Too Many Requests error response.

To request a rate limit increase contact support.

Errors

Advanced Server Access can return the following HTTP errors: