> For the complete documentation index, see [llms.txt](https://docs.blynk.io/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blynk.io/en/blynk.cloud/platform-https-api/authentication.md).
# Authentication
OAuth2 authentication endpoints for obtaining and refreshing access tokens
## Get access token using client credentials
> Authenticate using your OAuth2 client credentials to obtain an organization-level access token.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Authentication","description":"OAuth2 authentication endpoints for obtaining and refreshing access tokens"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic authentication using OAuth2 client credentials (base64-encoded `client_id:client_secret`)"}},"schemas":{"OAuth2Token":{"type":"object","description":"OAuth2 access token response.\n\n**Token lifetimes (subject to change):** Currently, access tokens expire after **24 hours** (86,400 seconds) and refresh tokens share the same lifetime. Always use the `expires_in` value from the response to determine the actual expiration rather than assuming a fixed TTL, as these defaults may be adjusted in the future.\n","properties":{"access_token":{"type":"string","description":"Access token for authenticating API requests. Use as `Bearer` token in the `Authorization` header."},"token_type":{"type":"string","enum":["Bearer"],"description":"Token type"},"expires_in":{"type":"integer","format":"int32","description":"Token expiration time in seconds. Currently defaults to 86,400 (24 hours). This value is subject to change — always rely on the returned value."},"refresh_token":{"type":"string","nullable":true,"description":"Refresh token for obtaining new access tokens. The refresh token currently shares the same lifetime as the access token (24 hours, subject to change). Each refresh token can only be used once."}},"required":["access_token","token_type","expires_in"]},"OAuth2ErrorResponse":{"type":"object","description":"OAuth2 error response following RFC 6749","properties":{"error":{"type":"string","description":"Error code","enum":["invalid_request","invalid_client","invalid_grant","unauthorized_client","unsupported_grant_type"]},"error_description":{"type":"string","description":"Human-readable error description"}},"required":["error","error_description"]}}},"paths":{"/oauth2/token?grant_type=client_credentials":{"post":{"tags":["Authentication"],"summary":"Get access token using client credentials","description":"Authenticate using your OAuth2 client credentials to obtain an organization-level access token.","operationId":"getAccessTokenByClientCredentials","parameters":[],"responses":{"200":{"description":"Access token issued successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuth2Token"}}}},"400":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuth2ErrorResponse"}}}},"500":{"description":"Internal server error"}}}}}}
```
## Get access token using user credentials
> Authenticate using OAuth2 client credentials along with the user's email and password to obtain a user-level access token.\
> The user must belong to the same organization (or its child) as the OAuth2 client.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Authentication","description":"OAuth2 authentication endpoints for obtaining and refreshing access tokens"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic authentication using OAuth2 client credentials (base64-encoded `client_id:client_secret`)"}},"schemas":{"OAuth2Token":{"type":"object","description":"OAuth2 access token response.\n\n**Token lifetimes (subject to change):** Currently, access tokens expire after **24 hours** (86,400 seconds) and refresh tokens share the same lifetime. Always use the `expires_in` value from the response to determine the actual expiration rather than assuming a fixed TTL, as these defaults may be adjusted in the future.\n","properties":{"access_token":{"type":"string","description":"Access token for authenticating API requests. Use as `Bearer` token in the `Authorization` header."},"token_type":{"type":"string","enum":["Bearer"],"description":"Token type"},"expires_in":{"type":"integer","format":"int32","description":"Token expiration time in seconds. Currently defaults to 86,400 (24 hours). This value is subject to change — always rely on the returned value."},"refresh_token":{"type":"string","nullable":true,"description":"Refresh token for obtaining new access tokens. The refresh token currently shares the same lifetime as the access token (24 hours, subject to change). Each refresh token can only be used once."}},"required":["access_token","token_type","expires_in"]},"OAuth2ErrorResponse":{"type":"object","description":"OAuth2 error response following RFC 6749","properties":{"error":{"type":"string","description":"Error code","enum":["invalid_request","invalid_client","invalid_grant","unauthorized_client","unsupported_grant_type"]},"error_description":{"type":"string","description":"Human-readable error description"}},"required":["error","error_description"]}}},"paths":{"/oauth2/token?grant_type=user_credentials":{"post":{"tags":["Authentication"],"summary":"Get access token using user credentials","description":"Authenticate using OAuth2 client credentials along with the user's email and password to obtain a user-level access token.\nThe user must belong to the same organization (or its child) as the OAuth2 client.\n","operationId":"getAccessTokenByUserCredentials","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userEmail":{"type":"string","format":"email","description":"User email address"},"password":{"type":"string","format":"password","description":"User password"}},"required":["userEmail","password"]}}}},"responses":{"200":{"description":"Access token issued successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuth2Token"}}}},"400":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuth2ErrorResponse"}}}},"500":{"description":"Internal server error"}}}}}}
```
## Refresh an access token
> Exchange a refresh token for a new access token.\
> Each refresh token can only be used \*\*once\*\* — after use, the previous refresh token is invalidated and a new one is returned.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Authentication","description":"OAuth2 authentication endpoints for obtaining and refreshing access tokens"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic authentication using OAuth2 client credentials (base64-encoded `client_id:client_secret`)"}},"schemas":{"OAuth2Token":{"type":"object","description":"OAuth2 access token response.\n\n**Token lifetimes (subject to change):** Currently, access tokens expire after **24 hours** (86,400 seconds) and refresh tokens share the same lifetime. Always use the `expires_in` value from the response to determine the actual expiration rather than assuming a fixed TTL, as these defaults may be adjusted in the future.\n","properties":{"access_token":{"type":"string","description":"Access token for authenticating API requests. Use as `Bearer` token in the `Authorization` header."},"token_type":{"type":"string","enum":["Bearer"],"description":"Token type"},"expires_in":{"type":"integer","format":"int32","description":"Token expiration time in seconds. Currently defaults to 86,400 (24 hours). This value is subject to change — always rely on the returned value."},"refresh_token":{"type":"string","nullable":true,"description":"Refresh token for obtaining new access tokens. The refresh token currently shares the same lifetime as the access token (24 hours, subject to change). Each refresh token can only be used once."}},"required":["access_token","token_type","expires_in"]},"OAuth2ErrorResponse":{"type":"object","description":"OAuth2 error response following RFC 6749","properties":{"error":{"type":"string","description":"Error code","enum":["invalid_request","invalid_client","invalid_grant","unauthorized_client","unsupported_grant_type"]},"error_description":{"type":"string","description":"Human-readable error description"}},"required":["error","error_description"]}}},"paths":{"/oauth2/token?grant_type=refresh_token":{"post":{"tags":["Authentication"],"summary":"Refresh an access token","description":"Exchange a refresh token for a new access token.\nEach refresh token can only be used **once** — after use, the previous refresh token is invalidated and a new one is returned.\n","operationId":"refreshAccessToken","parameters":[{"name":"refresh_token","in":"query","required":true,"schema":{"type":"string"},"description":"The refresh token obtained from a previous token response"}],"responses":{"200":{"description":"Access token refreshed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuth2Token"}}}},"400":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuth2ErrorResponse"}}}},"500":{"description":"Internal server error"}}}}}}
```
---
# 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.blynk.io/en/blynk.cloud/platform-https-api/authentication.md?ask=&goal=
```
`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.