-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update Cloud Client for new USER-scoped API tokens #1423
Merged
Merged
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,110 @@ | ||
# Prefect Cloud API | ||
|
||
Prefect Cloud exposes a powerful GraphQL API for interacting with the platform. There are a variety of ways you can access the API. | ||
|
||
# Authentication | ||
|
||
In order to interact with Cloud from your local machine, you'll need to generate an API token. | ||
|
||
To generate an API token, use the Cloud UI or the following GraphQL call (from an already authenticated client!): | ||
|
||
```graphql | ||
mutation { | ||
createAPIToken(input: { name: "My API token", role: USER }) { | ||
token | ||
} | ||
} | ||
``` | ||
|
||
## API Token Scopes | ||
|
||
Prefect Cloud can generate API tokens with three different scopes. | ||
|
||
### `USER` | ||
|
||
`USER`-scoped API tokens function as personal access tokens. These tokens have very few permissions on their own, but can be used to authenticate with the Cloud API. Once authenticated, `USER` tokens can be used to generate short-lived JWT auth tokens for any tenant the user belongs to. These auth tokens inherit any permissions the user has in that tenant, allowing full API access. The Client manages the process of provisioning and refreshing these tokens. | ||
|
||
### `TENANT` | ||
|
||
`TENANT`-scoped API tokens are used for long-lived programmatic access to a specific Cloud tenant. Unlike `USER` tokens, which can adopt any tenant membership the user has, `TENANT` tokens are fixed to a specific membership in a specific tenant. They adopt whatever permissions the user has in the tenant. | ||
|
||
### `AGENT` | ||
|
||
`AGENT`-scoped API tokens are used for processes like the Prefect Agent, which require the ability to execute flows on behalf of a tenant. Unlike the other token types, `AGENT` tokens are not scoped to a particular user. Consequently, they can only be generated by tenant admins. | ||
|
||
# Python Client | ||
|
||
## About the Client | ||
|
||
Prefect Core includes a Python client for Prefect Cloud. The Python client was designed for both interactive and programmatic use, and includes convenience methods for transparently managing authentication when used with `USER`-scoped tokens. | ||
|
||
## Getting started | ||
|
||
For interactive use, the most common way to use the Cloud Client is to generate a `USER`-scoped token and provide it to the client. After doing so, users can save the token so it persists across all Python sessions: | ||
|
||
```python | ||
import prefect | ||
client = prefect.Client(api_token="YOUR_USER_TOKEN") | ||
client.save_api_token() | ||
``` | ||
|
||
Now, starting a client in another session will automatically reload the token: | ||
|
||
```python | ||
client = prefect.Client() | ||
assert client._api_token == "YOUR_USER_TOKEN" # True | ||
``` | ||
|
||
Note that a token can be provided by environment variable (`PREFECT__CLOUD__AUTH_TOKEN`) or in your Prefect config (under `cloud.auth_token`). | ||
|
||
:::tip Using `USER` tokens | ||
The steps shown here were designed to be used with `USER`-scoped tokens. They will work with `TENANT` scoped tokens as well, but unexpected errors could result. | ||
::: | ||
|
||
Once provisioned with a `USER` token, the Cloud Client can query for available tenants and login to those tenants. In order to query for tenants, call: | ||
|
||
```python | ||
client.get_available_tenants() | ||
``` | ||
|
||
This will print the id, name, and slug of all the tenants the user can login to. | ||
|
||
```python | ||
client.login_to_tenant(tenant_slug='a-tenant-slug') | ||
# OR | ||
client.login_to_tenant(tenant_id='A_TENANT_ID') | ||
``` | ||
|
||
Both of these calls persist the active tenant in local storage, so you won't have to login again until you're ready to switch tenants. | ||
|
||
Once logged in, you can make any GraphQL query against the Cloud API: | ||
|
||
```python | ||
client.graphql( | ||
{ | ||
'query': { | ||
'flow': { | ||
'id' | ||
} | ||
} | ||
} | ||
) | ||
``` | ||
|
||
(Note that this illustrates how Prefect can parse Python structures to construct GraphQL query strings!) | ||
|
||
Finally, you can logout: | ||
|
||
```python | ||
client.logout_from_tenant() | ||
``` | ||
|
||
# GraphQL | ||
|
||
The Cloud API also supports direct GraphQL access. While you can still use `USER`-scoped tokens to access and log in to tenants, you will need to manage the short-lived auth and refresh tokens yourself. Therefore, we recommend using the Python client for `USER`-scoped access. | ||
|
||
For `TENANT`-scoped tokens, simply include the token as the authorization header of your GraphQL requests: | ||
|
||
```json | ||
{ "authorization": "Bearer YOUR_TOKEN" } | ||
``` |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
RUNNER
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
TY