Authentication, Scopes, Rate-Limiting

Authentication

The REST API uses Access token-based authentication. As an admin of your Tideways organization, you can create Access Tokens for any single organization that the user (Token owner) is a member of. Tokens are not connected to other organizations of the user.

You can generate Access tokens from the "Organizations" and then "API Access" settings menu, that is reachable from the dropdown menu in the top right. In the API access settings screen, click on "Generate API Token" to view the form that asks for a description of the purpose the token is used for your own reference and what scopes the token should have (see below for an explanation)

After generating, the API token is only showed to you once. You should copy it to a password manager or password vault mechanism within your company for future access.

Once you have an API token, you must send it as an HTTP Header with every request to the API, for example:

Authorization: Bearer YourTokenHere

If you are using cURL, for example on the command line, you can do this the following way:

curl -H "Authorization: Bearer YourTokenHere" https://app.tideways.io/apps/api/{organization}/{application}/issues

Scopes

: Every token can be assigned one ore several access scopes that limit the access to a subset of the API:

Metrics

Scoped tokens can access performance, errors and history API.

Traces

Scoped tokens can access trace data API.

Issues

Scoped token can access issue data API.

Users

Scoped token can access the Users API.

CLI

Scoped token can access the CLI / Trigger Trace API.

Rate-Limiting

We rate-limit access to the Tideways API, because several of the methods can be computationally intensive. After the limit is reached, an HTTP 429 error is thrown, until the hour is passed.

The rate limit depends on the license of the project.

License	Number of API Requests per Hour
Pro	2500
Standard	1000
Basic	250
Other Licenses	100

Whenever you make a request to the Tideways API, the server will return the rate limit and the current remaining requests for the hour as HTTP headers in the response. For example:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 989
X-RateLimit-Reset: 1526295600

Token Capabilities Endpoint

Every token can query the capabilities endpoint to get access to the list of granted scopes and all organizations and projects accessible via the token.

Requirements: You need an API access token with any scopes for this endpoint.

https://app.tideways.io/apps/api/_token

Here is an example request/response via cURL:

curl -H "Authorization: Bearer ..." -X GET \
    https://app.tideways.io/apps/api/_token -k
{
    "scopes":["metrics","errors"],
    "projects":[
        {"name":"demo\/foo","license":"pro"},
        {"name":"demo\/bar","license":"standard"}
    ]
}

Resources and Endpoints

Every resource in the REST API has its own documentation page:

The Performance Metrics API allows access to current performance of projects, services, environments and transactions summarized by time or other dimensions.
The Issues API allows access to recent issue data.
The History API allows access to the aggregated daily, weekly, monthly history of project performance.

Still need help? Email [email protected]