Update Cloud Client for new USER-scoped API tokens

[jlowin]

Thanks for contributing to Prefect!

Please describe your work and make sure your PR:

• adds new tests (if appropriate)
• updates CHANGELOG.md (if appropriate)
• updates docstrings for any new functions or function arguments, including docs/outline.toml for API reference docs (if appropriate)

Note that your PR will not be reviewed unless all three boxes are checked.

What does this PR change?

This PR adds a new auth flow to the Python Cloud client, without changing its existing behavior. However, it does rename some private attributes.

The primary contribution of this PR is to support USER-scoped Cloud API tokens, which function as personal access tokens. USER-scoped tokens can not be used to interact with the Cloud API in a significant way, but are able to authenticate with the API and receive short-lived JWTs in return. These JWTs are full auth tokens representing a user's membership in a specific Cloud tenant.

The user flow works like this:

1. User instantiates a Cloud client and passes it a USER-scoped API token
2. User calls client.save_api_token() to write the token to local storage so it persists across Python sessions.
3. User calls client.get_available_tenants() to see what tenants they can login to
4. User calls client.log_to_tenant(tenant_id=<>, tenant_slug=<>) (with one or the other argument). When this happens, an ephemeral JWT is received as well as a refresh token. Note this step is also persisted across sessions.
5. The User can now make API calls as if they were logged in to the tenant in question, for example client.graphql(...). The Client is managing all refreshing and exchanging of JWTs in the background.
6. The User is finished, so they call client.logout_from_tenant(). This discards the JWT access token.

The TOKEN- and AGENT- scoped flows are unchanged:

1. Client instantiated with an API token (or receives one via env var/config)
2. Client includes the API token in all calls.

[jlowin]

Note for review: many of the files are affected by the name changes (auth_token -> api_token), but almost the entire PR is contained in this commit: e5af2d6

[codecov]

Codecov Report

Merging #1410 into master will increase coverage by 0.05%.
The diff coverage is 98.93%.

[joshmeek]

Will this now work or will users still need to select a tenant? Should we make a CLI command to switch tenants?

[jlowin]

This will work fine with current API tokens that don't require selecting a tenant; it writes the token to disk (and recovers it) without regard for what token it is.

We should 100% make a CLI interface for this, but I wanted to get the machinery in first.

[joshmeek]

In a lot of places deployment related this is provided only as https://api.prefect.io because it was placed into graphql with {}/graphql/alpha so you should also update the defaults in all the agent code.

[jlowin]

I would say the fallback should actually remain api.prefect.io so that it isn't versioned, and the config should include the versioned API (which it now does). That way the agent code doesn't need updating in most scenarios, and does have a sane fallback (since the Agent will always be hitting the most current API -- the main reason for changing the config is so that users could store a separate API token for each endpoint during testing)

I think I got all of the places where graphql/alpha was being added manually, the only place I still see it in the codebase is config.toml

[cicdw]

Overall this looks solid, two comments and I'm going to do another pass

[cicdw]

For the record, this is a large breaking change - this means that once this agent is deployed, it can only deploy flows built off of the most recent version of Core.

[cicdw]

This includes the local agent.

[joshmeek]

Oh yeah this hadn’t occurred to me. Should we make it so that it places both API_TOKEN and AUTH_TOKEN in the images to maintain current compatibility?

[joshmeek]

Why was api removed?

[jlowin]

Closing for #1423 which does not have any breaking changes