Document how to authenticate with public API using a project key

railwayapp · Dec 21, 2024 · 06e49c6 · 06e49c6
1 parent 3ae70ba
commit 06e49c6
Show file tree

Hide file tree

Showing 2 changed files with 41 additions and 20 deletions.
diff --git 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.
 
 <Image src="https://res.cloudinary.com/railway/image/upload/v1667386744/docs/new-token-form_rhrbw8.png"
 alt="New token form"
 layout="responsive"
 width={1618 } height={378} quality={80} />
 
-#### 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: <PROJECT_TOKEN_GOES_HERE>' \
+  --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
@@ -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 <a href="https://railway.com/account/tokens" target="_blank">tokens page</a> 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 <a href="https://railway.com/account/tokens" target="_blank">tokens page</a> 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: <PROJECT_TOKEN_GOES_HERE>' \
+  --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.