Usage
Commands
Cloud

Architectures
Contributors

Contract

In order for Tuist’s cloud features to interact with HTTP servers, the exposed API needs to conform with the contract described in this page.

Base URL

In all the examples below, we are assuming that the project is pointing to a server with URL https://cloud.tuist.io

Authentication

User authentication

When using Tuist’s cloud features from a local environments, users will need to authenticate with the API. If the authentication is successful, a token will be generated and stored safely in the user’s environment. The generated token must be unique to the user and valid across all the projects the user has access to.

The authentication flow:

  1. When the user runs tuist cloud auth, Tuist sends the user to https://cloud.tuist.io/auth.
  2. The user authenticates on the server.
  3. When the authentication finishes, the server redirects the user to http://localhost:4545/auth.

The URL that triggers the call to localhost should include the any of the following attributes:

  • token and account: The generated token and the account identifier if the authentication was successful.
  • error: The error message if the authentication failed.
# A successful authentication
http://localhost:4455/auth?token=xyz
# An errored authentication
# Notice that the error argument has been escaped.
http://localhost:4455/auth?error=Couldn%27t%20find%20the%20current%20user
Copy the content
Authenticating users

How the server decides to authenticate the user is up to the server. However, we recommend authenticating using the version control provider (e.g. GitHub). That'll allow tying the project to a repository and leverage the API to know whether the user has access to the repository and therefore the project.

Continuous integration (CI) authentication

On CI, projects will authenticate using a secret token that is associated to the project. The variable should be present in the environment with the name TUIST_CLOUD_TOKEN. For security reasons, we recommend defining that variable as a secret variables.

Authentication header

Tuist will authenticate HTTP requests by including an Authorization header:

curl -v -H "Authorization: token TOKEN" https://cloud.tuist.io/api/...
Copy the content

Depending on the endpoint, the token will represent a project or a user. Each of the endpoints documented in the following sections will indicate what type of token is expected.