Authentication

OAuth2 authentication endpoints for obtaining and refreshing access tokens

Get access token using client credentials

post

Authenticate using your OAuth2 client credentials to obtain an organization-level access token.

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic authentication using OAuth2 client credentials (base64-encoded client_id:client_secret)

Responses

200

Access token issued successfully

application/json

OAuth2 access token response.

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.

access_tokenstringRequired

Access token for authenticating API requests. Use as Bearer token in the Authorization header.

Example: ct6Q2h1OiDHJaePbBgrpCgN3xfLPc9WYnCC6tRFd

token_typestring · enumRequired

Token type

Example: BearerPossible values:

expires_ininteger · int32Required

Token expiration time in seconds. Currently defaults to 86,400 (24 hours). This value is subject to change — always rely on the returned value.

Example: 86400

refresh_tokenstring · nullableOptional

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.

Example: fx8TlqzAxg5b8Ukzp46rD-FXpxrNxHKX3BZQjGhG

400

Authentication failed

application/json

500

Internal server error

post/oauth2/token?grant_type=client_credentials

HTTPcURLJavaScriptPython

POST /oauth2/token?grant_type=client_credentials HTTP/1.1
Host: blynk.cloud
Authorization: Basic username:password
Accept: */*

{
  "access_token": "ct6Q2h1OiDHJaePbBgrpCgN3xfLPc9WYnCC6tRFd",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "fx8TlqzAxg5b8Ukzp46rD-FXpxrNxHKX3BZQjGhG"
}

Get access token using user credentials

post

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.

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic authentication using OAuth2 client credentials (base64-encoded client_id:client_secret)

Body

application/json

userEmailstring · emailRequired

User email address

Example: [e-mail]

passwordstring · passwordRequired

User password

Example: mySecretPassword123

Responses

200

Access token issued successfully

application/json

OAuth2 access token response.

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.

access_tokenstringRequired

Access token for authenticating API requests. Use as Bearer token in the Authorization header.

Example: ct6Q2h1OiDHJaePbBgrpCgN3xfLPc9WYnCC6tRFd

token_typestring · enumRequired

Token type

Example: BearerPossible values:

expires_ininteger · int32Required

Token expiration time in seconds. Currently defaults to 86,400 (24 hours). This value is subject to change — always rely on the returned value.

Example: 86400

refresh_tokenstring · nullableOptional

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.

Example: fx8TlqzAxg5b8Ukzp46rD-FXpxrNxHKX3BZQjGhG

400

Authentication failed

application/json

500

Internal server error

post/oauth2/token?grant_type=user_credentials

cURLrequests

curl --request POST \
  --url 'https://blynk.cloud/oauth2/token?grant_type=user_credentials' \
  --header 'Authorization: Basic {clientId:clientSecret}' \
  --header 'Content-Type: application/json' \
  --data '{
    "userEmail": "[e-mail]",
    "password": "mySecretPassword123"
  }'

{
  "access_token": "ct6Q2h1OiDHJaePbBgrpCgN3xfLPc9WYnCC6tRFd",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "fx8TlqzAxg5b8Ukzp46rD-FXpxrNxHKX3BZQjGhG"
}

Refresh an access token

post

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.

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic authentication using OAuth2 client credentials (base64-encoded client_id:client_secret)

Query parameters

refresh_tokenstringRequired

The refresh token obtained from a previous token response

Responses

200

Access token refreshed successfully

application/json

OAuth2 access token response.

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.

access_tokenstringRequired

Access token for authenticating API requests. Use as Bearer token in the Authorization header.

Example: ct6Q2h1OiDHJaePbBgrpCgN3xfLPc9WYnCC6tRFd

token_typestring · enumRequired

Token type

Example: BearerPossible values:

expires_ininteger · int32Required

Token expiration time in seconds. Currently defaults to 86,400 (24 hours). This value is subject to change — always rely on the returned value.

Example: 86400

refresh_tokenstring · nullableOptional

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.

Example: fx8TlqzAxg5b8Ukzp46rD-FXpxrNxHKX3BZQjGhG

400

Authentication failed

application/json

500

Internal server error

post/oauth2/token?grant_type=refresh_token

HTTPcURLJavaScriptPython

POST /oauth2/token?grant_type=refresh_token?refresh_token=text HTTP/1.1
Host: blynk.cloud
Authorization: Basic username:password
Accept: */*

{
  "access_token": "ct6Q2h1OiDHJaePbBgrpCgN3xfLPc9WYnCC6tRFd",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "fx8TlqzAxg5b8Ukzp46rD-FXpxrNxHKX3BZQjGhG"
}

Introspect an access token

post

Determine whether an access token is currently active and, if so, return metadata about it (RFC 7662 style).

• The calling client authenticates with its own OAuth2 client credentials (HTTP Basic, same as /oauth2/token).

• The token to introspect must be sent in the request body as application/x-www-form-urlencoded (token=<token>). It is never accepted via the query string.

The endpoint always responds with 200 when the request and caller are valid. A token that is invalid, expired, or revoked (including OAuth client deletion/secret regeneration, user deactivation, or organization removal) is reported with the exact body {"active": false} and no reason detail. A token issued in another region is not present in this region's token store and is therefore also reported as {"active": false}.

The response schema is a stable, versioned contract — only additive changes will be made.

Authorizations

basicAuth

AuthorizationstringRequired

HTTP Basic authentication using OAuth2 client credentials (base64-encoded client_id:client_secret)

Body

application/x-www-form-urlencoded

tokenstringRequired

The access token to introspect.

Example: ct6Q2h1OiDHJaePbBgrpCgN3xfLPc9WYnCC6tRFd

Responses

200

Introspection result (always returned when the request and caller are valid)

application/json

Token introspection response (RFC 7662 style).

This schema is a stable, versioned contract: only additive changes are made. For an inactive token only the active field is present (the body is exactly {"active": false}); all other fields are omitted.

activebooleanRequired

Whether the token is currently active (valid, not expired, not revoked, and local to this region).

Example: true

org_idinteger · int32Optional

Organization the token belongs to. Present only for active tokens.

Example: 1

grant_typestring · enumOptional

The grant type the token was issued with. Present only for active tokens.

Example: user_credentialsPossible values:

client_idstringOptional

The OAuth2 client the token was issued to. Present only for active tokens.

Example: oa2-client-id_abc123

substring · nullableOptional

The user id the token is scoped to. Only present (non-null) for user-scoped tokens.

Example: 42

rolestring · nullableOptional

The user's organization role. Only present (non-null) for user-scoped tokens.

Example: Admin

expinteger · int64Optional

Expiration time in epoch seconds. Present for active tokens; omitted for permanent tokens.

Example: 1784106000

iatinteger · int64Optional

Issued-at time in epoch seconds. Present only for active tokens.

Example: 1784019600

token_typestring · enumOptional

Token type. Present only for active tokens.

Example: BearerPossible values:

400

Malformed request (e.g. missing token, token supplied in the query string, or wrong Content-Type)

application/json

401

Missing or invalid caller credentials

application/json

500

Internal server error

post/oauth2/introspect

cURL

curl --request POST \
  --url 'https://blynk.cloud/oauth2/introspect' \
  --header 'Authorization: Basic {clientId:clientSecret}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'token=ct6Q2h1OiDHJaePbBgrpCgN3xfLPc9WYnCC6tRFd'

{
  "active": true,
  "org_id": 1,
  "grant_type": "user_credentials",
  "client_id": "oa2-client-id_abc123",
  "sub": "42",
  "role": "Admin",
  "exp": 1784106000,
  "iat": 1784019600,
  "token_type": "Bearer"
}