> For the complete documentation index, see [llms.txt](https://docs.floral.fun/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.floral.fun/authentication/scopes-and-tokens.md).

# Scopes and tokens

## Scopes

| Scope           | Allows                                 |
| --------------- | -------------------------------------- |
| `profile:read`  | `GET /v1/users/me`                     |
| `quests:verify` | `POST /v1/quests/verify` for this user |

Public data (`GET /v1/users/{id}`, `/v1/users/{id}/posts`, `/v1/posts/{id}` and the community endpoints) needs a valid token but no scope.

Request only what you need. Users see each scope on the consent screen. A scope must be enabled for your application, or authorization returns `invalid_scope`.

A token carries the scopes requested for that authorization. If a user approves your application again with other scopes, the connection gains them. If you remove a scope from your application, it stops working at once, including on tokens already issued.

## Token lifetimes

| Token              | Prefix    | Lifetime                                              |
| ------------------ | --------- | ----------------------------------------------------- |
| Authorization code | `flr_ac_` | 5 minutes, single use                                 |
| Access token       | `flr_at_` | 1 hour                                                |
| Refresh token      | `flr_rt_` | 90 days from when it was issued, replaced on each use |
| App token          | `flr_ct_` | 1 hour                                                |

Treat tokens as opaque strings, because their format may change.

## Which token to use

|                          | User token                          | App token                                                     |
| ------------------------ | ----------------------------------- | ------------------------------------------------------------- |
| Client type              | Confidential or public              | Confidential only                                             |
| Get it from              | Floral Connect                      | `client_credentials`                                          |
| `GET /v1/users/me`       | Yes, with `profile:read`            | No                                                            |
| Public data              | Yes                                 | Yes                                                           |
| `POST /v1/quests/verify` | For that user, with `quests:verify` | For any user connected with `quests:verify`, naming `user_id` |

If you have a backend, linking once and then verifying with an app token means you don't have to store and refresh a token for each user. An app token keeps working for a connected user until they disconnect, even after their refresh token has expired.

## Refresh token rotation

Each refresh returns a new refresh token, and you must store it. The old one stops working.

Retrying a refresh within 10 seconds, for example after a dropped response, fails harmlessly. Reusing an old refresh token later is treated as theft and revokes every token from that sign-in, so the user has to reconnect. Avoid concurrent refreshes for the same user.

Redeeming an authorization code twice also revokes the tokens that code produced.

## App tokens

A `client_credentials` token acts as your platform rather than as a user:

```json
{ "user_id": "usr_123", "action": "follow_user", "target_id": "usr_789" }
```

An app token can't verify anyone who hasn't granted your platform `quests:verify`. Those requests return `403 user_not_linked`, whether or not the account exists.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.floral.fun/authentication/scopes-and-tokens.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.