diff --git a/src/docs/guides/public-api.md b/src/docs/guides/public-api.md index efe0b166a..9ca9e95a7 100644 --- a/src/docs/guides/public-api.md +++ b/src/docs/guides/public-api.md @@ -29,31 +29,32 @@ https://backboard.railway.com/graphql/v2 ### Creating a Token -To use the API, you will need an API token. You can create one by visiting the [tokens page](https://railway.com/account/tokens) in your account settings. There are two types of tokens you can create. +To use the API, you will need an API token. There are three types of tokens you can create. + +#### Team Token and Personal Token + +You can create an API token from the [tokens page](https://railway.com/account/tokens) in your account settings. New token form -#### Team Token - -Select a team in the `Team` dropdown to create a token tied to a team. A team token - -- Has access to all the team's resources -- Cannot be used to access your personal resources on Railway +- **Team token** - Select a team in the `Team` dropdown to create a token tied to a team. A team token has access to all the team's resources, and cannot be used to access your personal resources on Railway. Feel free to share this token with your teammates. +- **Personal token** - If you do not select a team, the token will be tied to your Railway account and will have access to all your resources. Do not share this token with anyone else. *Note that Teams are a Pro feature.* -#### Personal Token - -If you do not select a team, the token will be tied to your Railway account and will have access to all your resources. Do not share this token with anyone else. - #### Project Token +You can create a project token from the tokens page in your project settings. + Project tokens are scoped to a specific environment within a project and can only be used to authenticate requests to that environment. ### Execute a Test Query +#### Using a Team or Personal Token + Once you have your token, you can pass it within the `Authorization` header of your request. You can try the query below in the terminal of your choice. It should return your name and email on Railway: ```bash @@ -64,6 +65,18 @@ curl --request POST \ --data '{"query":"query { me { name email } }"}' ``` +#### Using a Project Token + +If you have a project token, you can use it to authenticate requests to a specific environment within a project. The query below should return the project and environment IDs: + +```bash +curl --request POST \ + --url https://backboard.railway.com/graphql/v2 \ + --header 'Project-Access-Token: ' \ + --header 'Content-Type: application/json' \ + --data '{"query":"query { projectToken { projectId environmentId } }"}' +``` + ## Viewing the Schema Use popular tools like [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/) to connect to the API and query the schema. Simply set up your connection with the endpoint and Authorization token, and fetch the schema. diff --git a/src/docs/reference/public-api.md b/src/docs/reference/public-api.md index 53866e6ac..40e1fcc3c 100644 --- a/src/docs/reference/public-api.md +++ b/src/docs/reference/public-api.md @@ -14,7 +14,14 @@ https://backboard.railway.com/graphql/v2 ## Authentication -To use the API, you will need an API token. You can create one by visiting the tokens page in your account settings. +To use the API, you will need an API token. There are three types of tokens you can create. + +#### Team Token and Personal Token + +You can create an API token by visiting the tokens page in your account settings. + +- **Team tokens** are tied to a team and will have access to all the team's resources. This token cannot be used to access your personal resources on Railway so feel free to share it with your teammates. +- **Non-team tokens** will be tied to your Railway account and will have access to all your resources. Do not share this token with anyone else. ```bash curl --request POST \ @@ -24,19 +31,20 @@ curl --request POST \ --data '{"query":"query { me { name email } }"}' ``` - -### Team Token - -Team tokens are tied to a team and will have access to all the team's resources. This token cannot be used to access your personal resources on Railway so feel free to share it with your teammates. - -### Personal Token - -Non-team tokens will be tied to your Railway account and will have access to all your resources. Do not share this token with anyone else. - #### Project Token +You can create a project token by visiting the tokens page in your project settings. + Project tokens are scoped to a specific environment within a project and can only be used to authenticate requests to that environment. +```bash +curl --request POST \ + --url https://backboard.railway.com/graphql/v2 \ + --header 'Project-Access-Token: ' \ + --header 'Content-Type: application/json' \ + --data '{"query":"query { projectToken { projectId environmentId } }"}' +``` + ## Schema The Railway API supports introspection meaning you can use popular tools like [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/) to query the schema. Simply set up your connection with the endpoint and Authorization token, and fetch the schema.