> For the complete documentation index, see [llms.txt](https://docs.pulsoid.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pulsoid.net/access-token-management/oauth2-authorization-code-grant.md).

# OAuth2 Authorization Code Grant

NOTE: Authroization Code Grant Type flow requires trusted server. [“Authorization Code Grant” in the OAuth2 RFC](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1)

1. Send the user you want to authenticate to your registered redirect URI. An authorization page will ask the user to sign up or log into Pulsoid and allow the user to choose whether to authorize your application/identity system.

Create a `<a href="">login</a>`:

```bash
GET https://pulsoid.net/oauth2/authorize
    ?client_id=<your client ID>
    &redirect_uri=<your registered redirect URI>
    &response_type=code
    &scope=<space-separated list of scopes>
    &state=<unique token, generated by your application>
```

Parameters explained:

<table><thead><tr><th width="190.33333333333331">Name</th><th width="181">Type</th><th>Description</th></tr></thead><tbody><tr><td>client_id</td><td>string</td><td>Your client ID.</td></tr><tr><td>redirect_uri</td><td>string</td><td>Your registered redirect URI. This must exactly match the redirect URI registered in the prior.</td></tr><tr><td>response_type</td><td>string</td><td>Should be always <code>code</code></td></tr><tr><td>scope</td><td>string</td><td>Comma-separated list of scopes.</td></tr><tr><td>state</td><td>string</td><td>Your unique token, generated by your application. This is an OAuth 2.0 opaque value, used to avoid CSRF attacks. This value is echoed back in the response.</td></tr></tbody></table>

In our example, you request access to read heart rate data and send the user to <http://localhost>:

```bash
GET 'https://pulsoid.net/oauth2/authorize?response_type=code&client_id=3d3fa070-8358-4984-ae32-94392185df63&redirect_uri=http://localhost&scope=data:heart_rate:read&state=a52beaeb-c491-4cd3-b915-16fed71e17a8'
```

2. If the user authorizes your application, the user is redirected to your redirect URL:

```url
https://<your registered redirect URI>/?code=<authorization code>&state=<echoed back state your application path on authorization step>
```

The OAuth 2.0 authorization code is a randomly generated string. It is used in the next step, a request made to the token endpoint in exchange for an access token. In our example, your user gets redirected to:

```bash
http://localhost/?code=fedc8790-df28-4928-9dcf-55a4d7aa1f5e
    &state=a52beaeb-c491-4cd3-b915-16fed71e17a8
```

3. On your server, get an access token by making this request:

```bash
POST https://pulsoid.net/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id=<your client ID>
&client_secret=<your client secret>
&code=<authorization code received above>
&grant_type=authorization_code
&redirect_uri=<your registered redirect URI>
```

Here is a sample request:

```bash
POST https://pulsoid.net/oauth2/token
Content-Type: application/x-www-form-urlencoded   

grant_type=authorization_code 
&code=fedc8790-df28-4928-9dcf-55a4d7aa1f5e
&client_id=3d3fa070-8358-4984-ae32-94392185df63
&client_secret=a8262283-f568-4ec3-be84-1c4758dc1a82
&redirect_uri=http://localhost
```

4. We respond with a JSON-encoded access token. The response looks like this:

```bash
{
  "access_token": "<user access token>",
  "refresh_token": "<refresh token>",
  "expires_in": <number of seconds until the token expires>,
  "token_type": "bearer"
}
```

In our example:

```bash
{
  "access_token": "17ebb971-f558-48f2-81b1-788ea927c509",
  "refresh_token": "c6f30bc4-9a04-4e66-a1a1-080fad703a9e",
  "expires_in": 3600,
  "token_type": "bearer"
}
```

Note that code can be exchanged for an access token only once.

[How To Refresh Authorization Token?](/access-token-management/oauth2-refreshing-the-token.md)

[How To Validate Authorization Token?](/access-token-management/validate-authorization-token.md)


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.pulsoid.net/access-token-management/oauth2-authorization-code-grant.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.