Blyk

Developers

Documentation for the Bot API and Sign in with Blyk (OAuth 2.0).

Sign in with Blyk — OAuth 2.0Version 1.0.0

OAuth 2.0

Sign in with Blyk for your website or app: authorization code, PKCE and access tokens.

  1. Register your app
  2. Send the user to /authorize
  3. Exchange the code for a token
Base URLhttps://gateway.blyk.chat

"Sign in with Blyk" is an OAuth 2.0 authorization server (RFC 6749). Your site or app sends a person to a Blyk page, the person signs in and grants access, and you get a token — and with it, their profile: id, name, tag and photo. Your app never sees the person's Blyk password.

What is supported

  • Authorization Code (RFC 6749 §4.1) with PKCE (RFC 7636, S256 only) and renewal with a refresh token (§6). No other flows: no implicit, password, client credentials or device flow.
  • Server metadata — RFC 8414 (/.well-known/oauth-authorization-server).
  • Token revocation — RFC 7009 (/oauth/revoke).
  • Profile — /oauth/userinfo with a Bearer token (RFC 6750).
  • The iss parameter in the authorization response — RFC 9207.
  • OpenID Connect is not supported: no id_token, no /.well-known/openid-configuration, no JWKS and no openid scope. Tokens are opaque strings, not JWTs: there is no signature to verify — ask /oauth/userinfo who owns a token.
  • There is no introspection endpoint (RFC 7662) and no dynamic client registration (RFC 7591): apps are registered manually, in the Blyk app.

Endpoints

what address
issuer https://gateway.blyk.chat
sign-in and consent GET https://app.blyk.chat/oauth/authorize
tokens POST https://gateway.blyk.chat/oauth/token
revocation POST https://gateway.blyk.chat/oauth/revoke
profile GET https://gateway.blyk.chat/oauth/userinfo
metadata GET https://gateway.blyk.chat/.well-known/oauth-authorization-server

The sign-in page lives in the web app (app.blyk.chat); everything else is on the gateway (gateway.blyk.chat). The test environment has the same paths on test-app.blyk.chat and test-gateway.blyk.chat; apps and accounts there are separate.

Registering an app

Apps are registered only in the web version of Blyk (app.blyk.chat): the mobile apps do not have these screens. The interface is in Russian; the Russian labels are given in brackets.

  1. Open the "You" ("Вы") → "Development" ("Разработка") → "My apps" ("Мои приложения") tab and press "Create app" ("Создать приложение").
  2. Fill in how people will see it: name (1–64 characters), description (optional, up to 500), website (https://…) and icon. The name, icon and website are shown on the "Sign in with Blyk" screen.
  3. Add redirect URIs — 1 to 10, each up to 512 characters. They are compared character by character, so register exactly the value you will pass as redirect_uri:
    • https:// — any;
    • http:// — only to the local machine: localhost, 127.0.0.1, [::1] (for development and desktop apps). The port is part of the address: http://localhost:3000/cb and http://localhost:5173/cb are different URIs — register the ones you need;
    • a custom mobile app scheme — only with a dot in it, e.g. com.example.app:/oauth/cb (RFC 8252 §7.1);
    • no #fragment; javascript:, data:, file: and the like are rejected.
  4. Choose the client type — it cannot be changed later:
    • Confidential ("Конфиденциальный") — for a site with its own server: the code is exchanged with the secret, PKCE is optional (we still recommend it always).
    • Public ("Публичный") — for SPAs and mobile apps that cannot keep a secret: no secret, PKCE (S256) is mandatory.
  5. Press "Save" ("Сохранить"). The "Keys" ("Ключи") section shows the client_id (blyk_ + 24 hex characters) and, for a confidential client, the client_secret (blyk_cs_…). The secret is shown once and cannot be shown again. Lost it — "Generate a new secret" ("Сгенерировать новый секрет"): the old one stops working immediately.

One account can own up to 20 apps. Deleting an app is irreversible: sign-in stops working for everyone and all issued tokens die immediately.

The flow step by step

  1. Generate a random state (CSRF protection) and a code_verifier (PKCE), compute the code_challenge, and store state and code_verifier on your side — in the server session or in sessionStorage.
  2. Send the browser to https://app.blyk.chat/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&scope=profile&state=…&code_challenge=…&code_challenge_method=S256.
  3. The person signs in to Blyk (if not signed in yet), picks an account and sees the consent screen: your app's name and icon and the list of permissions. If this account has already granted your app the same permissions, the consent screen is skipped and Blyk sends the person straight back.
  4. Blyk redirects the browser to redirect_uri: ?code=blyk_ac_…&state=…&iss=https://gateway.blyk.chat — or ?error=access_denied&state=…&iss=… if the person pressed "Cancel".
  5. Check state (matches the stored one) and iss (equals https://gateway.blyk.chat). On mismatch, abort.
  6. Exchange the code for tokens: POST /oauth/token with grant_type=authorization_code, code, the same redirect_uri and code_verifier. The code lives 60 seconds and works once.
  7. Find out who signed in: GET /oauth/userinfo with Authorization: Bearer <access_token>. Link accounts by the sub field — it never changes; the name and tag can.
  8. Refresh the access token with the refresh_token when it expires (after an hour) — POST /oauth/token with grant_type=refresh_token. Store the new refresh token every time.
  9. On sign-out, revoke the refresh token: POST /oauth/revoke.

When a person grants your app access for the first time (or grants new permissions), Blyk tells them so in a service chat, with a link to "Connected apps" where access can be revoked.

PKCE

PKCE (RFC 7636) makes an intercepted code useless: only whoever knows the code_verifier can exchange the code, and only its hash — the code_challenge — travels in the URL.

  • code_verifier — 43–128 characters from A–Z a–z 0–9 - . _ ~, cryptographically random.
  • code_challenge = BASE64URL(SHA256(code_verifier)) without = — of the raw 32 bytes of the hash, exactly 43 characters. Not a hex string and not base64 of hex.
  • code_challenge_method — S256 only. plain is accepted from no one.
  • PKCE is mandatory for public clients and optional for confidential ones. But if the authorization request had a code_challenge, the exchange must carry the code_verifier; and conversely, a code_verifier without a code_challenge is rejected (invalid_grant).
// Browser or Node 18+: Web Crypto.
function base64url(bytes) {
  let s = '';
  for (const b of new Uint8Array(bytes)) s += String.fromCharCode(b);
  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

// 32 random bytes → 43 base64url characters.
const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
const challenge = base64url(
  await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier)),
);
const state = base64url(crypto.getRandomValues(new Uint8Array(16)));

The same in shell:

VERIFIER=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n')
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=\n')

Scopes

scope grants
profile id, name, tag and profile photo (/oauth/userinfo). Chats, contacts and email stay closed.

There is one scope today. scope is space-separated; missing or empty means profile. An unknown scope is invalid_scope. Consent is remembered as a union: having once granted more, the person will not see the consent screen when asked for less.

Lifetimes and limits

what value
authorization code 60 seconds, single use
access token 1 hour (expires_in: 3600)
refresh token 30 days from issue; each refresh issues a new one for another 30 days
picture in the profile signed URL, valid for a day
metadata cached for 5 minutes (Cache-Control: public, max-age=300)
request body of /oauth/token, /oauth/revoke up to 16 KB
state up to 1024 characters
apps per account 20
redirect URIs per app 1–10, each up to 512 characters

Prefixes make Blyk tokens recognisable in logs and to leak scanners: blyk_ac_ — code, blyk_at_ — access, blyk_rt_ — refresh, blyk_cs_ — client secret. Do not hard-code the length or shape of the rest.

Refresh token rotation and replay protection

  • Every refresh invalidates the presented refresh token and issues a new pair.
  • Presenting an already used refresh token signals theft: Blyk answers invalid_grant and revokes the whole chain — every access and refresh token issued for that sign-in, including the newest ones. The person has to sign in again.
  • Two concurrent refreshes with the same refresh token look exactly like a replay: one succeeds, the other kills the chain. Refresh strictly one at a time (a queue or a per-user lock).
  • An authorization code presented a second time also revokes everything already issued for it.

Tokens also stop working when the person disconnects your app ("Development" → "Connected apps"), deletes their account or is banned, and when the app is deleted.

Security

  • Always send and check state; check iss in the authorization response.
  • Use PKCE in confidential clients too.
  • The client secret belongs on the server only. Never put it in an SPA, a mobile app or a repository; if it leaks, generate a new one.
  • Store tokens like passwords: on the server, in encrypted storage or in the OS secure store. Token responses come with Cache-Control: no-store.
  • The sign-in page refuses to open inside an <iframe> (clickjacking protection): use a full-page redirect or a popup.
  • /oauth/token, /oauth/revoke, /oauth/userinfo and the metadata answer with Access-Control-Allow-Origin: * and read no cookies: a public client can exchange the code straight from the browser.
  • An access token in the URL (?access_token=) is not accepted — only in the Authorization header or a POST body.

Errors

Errors follow RFC 6749 §5.2 and RFC 6750 §3: JSON {"error": "<code>"}. There is no error_description: the code and the HTTP status are all the server says. On /oauth/authorize the error arrives as redirect URI parameters.

code HTTP when
invalid_request 400 a required parameter is missing, a parameter is repeated, the secret is both in Authorization and in the body, wrong HTTP method (then 405); on /authorize — no response_type, no PKCE from a public client, method other than S256, code_challenge not 43 base64url characters, state longer than 1024
invalid_client 401 unknown client_id, wrong or missing secret of a confidential client, a secret sent by a public client
invalid_grant 400 code or refresh token unknown, expired, already used or issued to another client; wrong redirect_uri or code_verifier; app disconnected; account deleted or banned
unsupported_grant_type 400 grant_type is neither authorization_code nor refresh_token
invalid_scope 400 unknown scope; on refresh — a scope wider than granted
unsupported_response_type — /authorize: response_type is not code
access_denied — /authorize: the person pressed "Cancel"
invalid_token 401 /userinfo: no token, or it is expired, revoked or unknown
server_error 500 a failure on Blyk's side
temporarily_unavailable 503 the authorization service did not answer in time — retry later

If the client_id is unknown or the redirect_uri is not registered, Blyk does not redirect the person back to you (the address is not verified) — the error is shown on the sign-in page.

Methods

Authorization

The person's sign-in and consent in the browser. The page is part of the web app (app.blyk.chat), not the gateway.

get/oauth/authorize

Sign-in and consent

Not called from code: the person's browser navigates here — as a full page or in a popup (not in an <iframe>: the page will not open there).

The page asks the person to sign in to Blyk if needed, lets them pick an account and shows the consent screen. The decision comes back as a browser redirect to redirect_uri (see the authorizationResponse callback):

  • "Allow" — code, state, iss;
  • "Cancel" — error=access_denied, state, iss;
  • invalid request — error=<code>, state, iss.

Your redirect URI's own query parameters (…/cb?tenant=1) are kept; Blyk's parameters are added to them.

An unknown client_id or an unregistered redirect_uri never redirects to you: the error stays on the Blyk page.

If this account has already granted your app the requested scopes, the consent screen is skipped and the browser comes straight back with a code. There is no prompt parameter (to force asking again).

Parameters

response_typestringrequiredin query

code only. Any other value — unsupported_response_type; missing — invalid_request.

code
client_idstringrequiredin query

The app's client_id from "My apps". Unknown — an error on the Blyk page, no redirect to you.

len 0…64
redirect_uristringoptionalin query

One of the registered redirect URIs, character for character. May be omitted only if the app has exactly one. No match — an error on the Blyk page, no redirect to you. If you pass it here, pass the same value to /oauth/token; if you omit it here, omit it there too.

len 0…512
scopestringoptionalin query

Space-separated scopes. Missing or empty — profile. Unknown scope — invalid_scope.

= "profile"
statestringoptionalin query

A random anti-CSRF value; returned unchanged. Formally optional, but always send it. Up to 1024 characters; longer — invalid_request.

len 0…1024
code_challengestringoptionalin query

PKCE: BASE64URL(SHA256(code_verifier)) without =, exactly 43 characters. Mandatory for public clients; optional for confidential ones, but we recommend it always.

len 43…43/^[A-Za-z0-9_-]{43}$/
code_challenge_methodstringoptionalin query

S256 only. Required together with code_challenge; must not be sent without it. plain — invalid_request.

S256

Responses

200
string

The HTML sign-in and consent page (the Blyk web app). Served with X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none'. The result is not in this response but in the browser redirect to redirect_uri.

Request
curl 'https://app.blyk.chat/oauth/authorize?response_type=code&client_id=blyk_3f9a1c0e7b2d4a6c8e0f1a2b&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&scope=profile&state=4kq0vZb3Yt8sQm1xWc7pLg&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256'
Response
<!doctype html><html lang="ru">…</html>
Methods

Tokens

Code exchange, refresh and revocation.

post/oauth/token

Get or refresh tokens

Two kinds of request, by grant_type:

  • authorization_code — exchange the code from the redirect for a token pair;
  • refresh_token — a new pair for a refresh token. The presented refresh token dies; presenting it again revokes the whole chain.

The body is application/x-www-form-urlencoded, not JSON. Each parameter at most once.

Client authentication:

client method (token_endpoint_auth_method)
confidential Authorization: Basic base64(client_id:client_secret) (client_secret_basic; client_id and secret are form-encoded first, RFC 6749 §2.3.1) or client_id + client_secret in the body (client_secret_post)
public client_id in the body only (none); sending a secret is invalid_client

Both methods at once (Basic and client_secret in the body) — invalid_request.

# Confidential client: code → tokens
curl -u "$CLIENT_ID:$CLIENT_SECRET" https://gateway.blyk.chat/oauth/token \
  -d grant_type=authorization_code -d code="$CODE" \
  -d redirect_uri=https://example.com/oauth/callback \
  -d code_verifier="$VERIFIER"

# Public client: refresh
curl https://gateway.blyk.chat/oauth/token \
  -d grant_type=refresh_token -d refresh_token="$REFRESH" \
  -d client_id="$CLIENT_ID"

Request body application/x-www-form-urlencoded AuthorizationCodeTokenRequest | RefreshTokenRequest

Token request parameters. The fields depend on grant_type.

Responses

200
TokenResponse

A new token pair.

400
OAuthError

Protocol refusal: invalid_request, invalid_grant, unsupported_grant_type or invalid_scope.

401
OAuthError

invalid_client: unknown client_id, wrong or missing secret of a confidential client, a secret sent by a public client. If the client used Authorization: Basic, the response carries WWW-Authenticate: Basic realm="blyk".

405
OAuthError

Wrong HTTP method. The Allow header lists the permitted ones.

500
OAuthError

A failure on Blyk's side. The request can be retried.

503
OAuthError

The authorization service is unavailable or did not answer within 10 seconds. Retry later.

Request
curl -X POST 'https://gateway.blyk.chat/oauth/token' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=blyk_ac_q2V3n8Jw0XoT5bLr1cYh7uPz4kDf9sGe6aMi2NtR0vE' \
  --data-urlencode 'redirect_uri=https://example.com/oauth/callback' \
  --data-urlencode 'code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk' \
  --data-urlencode 'client_id=blyk_3f9a1c0e7b2d4a6c8e0f1a2b'
Response
{
  "access_token": "blyk_at_Xc4m0Qv9Jp2sTn7eWb1yLk5rHd8gZa3uFo6iNq0tVw",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "blyk_rt_Pm7bR2xKc9vLq4tNw0eYs1gHj6uZa8dFo3iVk5nTr",
  "scope": "profile"
}
post/oauth/revoke

Revoke a token

Revocation per RFC 7009. The client authenticates the same way as on /oauth/token.

  • Revoking a refresh token kills the whole chain: the token itself and every access token issued for that sign-in.
  • Revoking an access token kills only that token.
  • An unknown, foreign (issued to another client) or already revoked token is also 200: the response does not reveal whether a token exists.

The person's consent stays: on the next sign-in the consent screen will not show. Only the person can disconnect the app completely — in "Connected apps".

curl -u "$CLIENT_ID:$CLIENT_SECRET" https://gateway.blyk.chat/oauth/revoke \
  -d token="$REFRESH" -d token_type_hint=refresh_token

Request body application/x-www-form-urlencoded RevokeRequest

The token to revoke.

tokenstringrequired

An access or refresh token of this client.

token_type_hintstringoptional

A hint about the token kind. Accepted but not needed — Blyk determines the kind itself.

access_tokenrefresh_token
client_idstringoptional

client_id. Required unless the client authenticates with Authorization: Basic.

client_secretstringoptional

Confidential client's secret (client_secret_post).

Responses

200

Done (or there was no such token). No body.

400
OAuthError

invalid_request: no token, a repeated parameter, or the client authenticated in two ways at once.

401
OAuthError

invalid_client: unknown client_id, wrong or missing secret of a confidential client, a secret sent by a public client. If the client used Authorization: Basic, the response carries WWW-Authenticate: Basic realm="blyk".

405
OAuthError

Wrong HTTP method. The Allow header lists the permitted ones.

500
OAuthError

A failure on Blyk's side. The request can be retried.

503
OAuthError

The authorization service is unavailable or did not answer within 10 seconds. Retry later.

Request
curl -X POST 'https://gateway.blyk.chat/oauth/revoke' \
  --data-urlencode 'token=blyk_rt_Pm7bR2xKc9vLq4tNw0eYs1gHj6uZa8dFo3iVk5nTr' \
  --data-urlencode 'token_type_hint=refresh_token'
Response
// Done (or there was no such token). No body.
Methods

User

Profile of the person who signed in with Blyk.

get/oauth/userinfo

Signed-in profile

Who owns the access token. The token goes in the Authorization: Bearer … header. It is not accepted in the URL (?access_token=).

Fields by scope:

scope fields
always sub, id
profile name, display_name, username, preferred_username, picture, avatar_url

Fields without a value are omitted entirely: no tag — no username and preferred_username; no photo — no picture and avatar_url.

This is not OpenID Connect UserInfo, even though sub, name, preferred_username and picture share the names: there is no id_token, and Blyk does not return email.

curl -H "Authorization: Bearer $ACCESS" https://gateway.blyk.chat/oauth/userinfo

Responses

200
UserInfo

The profile. The set of fields depends on the token's scopes.

401
OAuthError

invalid_token: no token, or it is expired, revoked or unknown, or the account is deleted or banned. Get a new one with the refresh token or ask the person to sign in again.

405
OAuthError

Wrong HTTP method. The Allow header lists the permitted ones.

500
OAuthError

A failure on Blyk's side. The request can be retried.

503
OAuthError

The authorization service is unavailable or did not answer within 10 seconds. Retry later.

Request
curl 'https://gateway.blyk.chat/oauth/userinfo'
Response
{
  "sub": "7349016627290100000",
  "id": "7349016627290100000",
  "name": "Alex",
  "display_name": "Alex",
  "username": "alex",
  "preferred_username": "alex",
  "picture": "https://files.blyk.chat/s/av_7Kq2…?vt=…",
  "avatar_url": "https://files.blyk.chat/s/av_7Kq2…?vt=…"
}
post/oauth/userinfo

Signed-in profile (POST)

Same as GET. The token goes in the Authorization: Bearer … header or as the access_token field of an application/x-www-form-urlencoded body (RFC 6750 §2.2). The header, if present, wins over the body.

Request body application/x-www-form-urlencoded UserInfoFormRequest

Needed only if the token is not in the header.

access_tokenstringoptional

Access token — if not sent in the Authorization header.

Responses

200
UserInfo

The profile. The set of fields depends on the token's scopes.

401
OAuthError

invalid_token: no token, or it is expired, revoked or unknown, or the account is deleted or banned. Get a new one with the refresh token or ask the person to sign in again.

500
OAuthError

A failure on Blyk's side. The request can be retried.

503
OAuthError

The authorization service is unavailable or did not answer within 10 seconds. Retry later.

Request
curl -X POST 'https://gateway.blyk.chat/oauth/userinfo' \
  --data-urlencode 'access_token=blyk_at_Xc4m0Qv9Jp2sTn7eWb1yLk5rHd8gZa3uFo6iNq0tVw'
Response
{
  "sub": "7349016627290100000",
  "id": "7349016627290100000",
  "name": "Alex",
  "display_name": "Alex",
  "username": "alex",
  "preferred_username": "alex",
  "picture": "https://files.blyk.chat/s/av_7Kq2…?vt=…",
  "avatar_url": "https://files.blyk.chat/s/av_7Kq2…?vt=…"
}
Methods

Service

Authorization server metadata for automatic client configuration.

get/.well-known/oauth-authorization-server

Server metadata

The RFC 8414 document: the server's endpoints and capabilities. OAuth libraries can configure themselves from it — give them the issuer https://gateway.blyk.chat.

HEAD is supported too. The response is cached for 5 minutes.

There is no /.well-known/openid-configuration and no jwks_uri: OpenID Connect is not supported.

Responses

405

Not GET/HEAD. No body.

500
OAuthError

A failure on Blyk's side. The request can be retried.

503
OAuthError

The authorization service is unavailable or did not answer within 10 seconds. Retry later.

Request
curl 'https://gateway.blyk.chat/.well-known/oauth-authorization-server'
Response
{
  "issuer": "https://gateway.blyk.chat",
  "authorization_endpoint": "https://app.blyk.chat/oauth/authorize",
  "token_endpoint": "https://gateway.blyk.chat/oauth/token",
  "revocation_endpoint": "https://gateway.blyk.chat/oauth/revoke",
  "userinfo_endpoint": "https://gateway.blyk.chat/oauth/userinfo",
  "scopes_supported": [
    "profile"
  ],
  "response_types_supported": [
    "code"
  ],
  "response_modes_supported": [
    "query"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],
  "revocation_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],
  "authorization_response_iss_parameter_supported": true
}
Objects

Objects

AuthorizationCodeTokenRequest

object

Exchanging an authorization code for tokens (RFC 6749 §4.1.3, RFC 7636 §4.5).

grant_typestringrequired

Request kind.

authorization_code
codestringrequired

The code from the redirect. 60 seconds, single use; presenting it again revokes everything issued for it.

redirect_uristringoptional

Exactly the same redirect_uri as in the authorization request. If it was not sent there, do not send it here either: any mismatch, including an extra parameter, is invalid_grant.

code_verifierstringoptional

The PKCE verifier. Required if the authorization had a code_challenge; forbidden if it did not.

len 43…128
client_idstringoptional

client_id. Required unless the client authenticates with Authorization: Basic (a public client or client_secret_post).

client_secretstringoptional

Confidential client's secret (client_secret_post). Not together with Basic; never for a public client.

{
  "grant_type": "authorization_code",
  "code": "blyk_ac_q2V3n8Jw0XoT5bLr1cYh7uPz4kDf9sGe6aMi2NtR0vE",
  "redirect_uri": "https://example.com/oauth/callback",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "client_id": "blyk_3f9a1c0e7b2d4a6c8e0f1a2b"
}

RefreshTokenRequest

object

A new token pair for a refresh token (RFC 6749 §6). The presented refresh token dies; store the new one from the response.

grant_typestringrequired

Request kind.

refresh_token
refresh_tokenstringrequired

The latest refresh token you received. An already used one — invalid_grant and the whole chain is revoked.

scopestringoptional

Narrow the new pair's scopes. Missing — the same as before. Wider than granted — invalid_scope.

client_idstringoptional

client_id. Required unless the client authenticates with Authorization: Basic.

client_secretstringoptional

Confidential client's secret (client_secret_post).

{
  "grant_type": "refresh_token",
  "refresh_token": "blyk_rt_Pm7bR2xKc9vLq4tNw0eYs1gHj6uZa8dFo3iVk5nTr",
  "client_id": "blyk_3f9a1c0e7b2d4a6c8e0f1a2b"
}

TokenResponse

object

A token pair (RFC 6749 §5.1).

access_tokenstringrequired

Access token for /oauth/userinfo. An opaque string prefixed blyk_at_.

token_typestringrequired

Always Bearer.

Bearer
expires_inintegerrequired

Access token lifetime in seconds. Currently 3600.

refresh_tokenstringrequired

A new refresh token (prefix blyk_rt_), valid for 30 days. Comes with every exchange and refresh; the previous one is invalid afterwards.

scopestringrequired

Granted scopes, space-separated.

{
  "access_token": "blyk_at_Xc4m0Qv9Jp2sTn7eWb1yLk5rHd8gZa3uFo6iNq0tVw",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "blyk_rt_Pm7bR2xKc9vLq4tNw0eYs1gHj6uZa8dFo3iVk5nTr",
  "scope": "profile"
}

RevokeRequest

object

Revocation request (RFC 7009 §2.1).

tokenstringrequired

An access or refresh token of this client.

token_type_hintstringoptional

A hint about the token kind. Accepted but not needed — Blyk determines the kind itself.

access_tokenrefresh_token
client_idstringoptional

client_id. Required unless the client authenticates with Authorization: Basic.

client_secretstringoptional

Confidential client's secret (client_secret_post).

{
  "token": "blyk_rt_Pm7bR2xKc9vLq4tNw0eYs1gHj6uZa8dFo3iVk5nTr",
  "token_type_hint": "refresh_token"
}

UserInfoFormRequest

object

The token in a POST body (RFC 6750 §2.2).

access_tokenstringoptional

Access token — if not sent in the Authorization header.

{
  "access_token": "blyk_at_Xc4m0Qv9Jp2sTn7eWb1yLk5rHd8gZa3uFo6iNq0tVw"
}

UserInfo

object

The person's profile. Empty fields are omitted. The pairs name/display_name, username/preferred_username, picture/avatar_url carry the same value under two names, for libraries with different expectations.

substringrequired

Blyk user id — a string of digits (a snowflake; it does not fit in a float64). Permanent; link accounts by it.

idstringrequired

Same as sub.

namestringoptional

Display name. Scope profile. The person can change it.

display_namestringoptional

Same as name.

usernamestringoptional

Tag (@alex without the @). Scope profile. No tag — no field. Can change.

preferred_usernamestringoptional

Same as username.

picturestring (uri)optional

Profile photo. Scope profile. Usually a signed URL of the Blyk file server, valid for a day: if you need the image longer, copy it to your side. No photo — no field.

avatar_urlstring (uri)optional

Same as picture.

{
  "sub": "7349016627290100000",
  "id": "7349016627290100000",
  "name": "Alex",
  "display_name": "Alex",
  "username": "alex",
  "preferred_username": "alex",
  "picture": "https://files.blyk.chat/s/av_7Kq2…?vt=…",
  "avatar_url": "https://files.blyk.chat/s/av_7Kq2…?vt=…"
}

AuthorizationServerMetadata

object

Authorization server metadata (RFC 8414 §2).

issuerstring (uri)required

The issuer. The authorization response's iss carries the same value.

authorization_endpointstring (uri)required

Sign-in and consent page (in the web app, on another domain).

token_endpointstring (uri)required

Code exchange and token refresh.

revocation_endpointstring (uri)optional

Token revocation (RFC 7009).

userinfo_endpointstring (uri)optional

Profile by access token.

scopes_supportedstring[]optional

Known scopes.

response_types_supportedstring[]required

code only.

response_modes_supportedstring[]optional

The authorization response comes as query parameters only (query).

grant_types_supportedstring[]optional

Supported grant_type values.

code_challenge_methods_supportedstring[]optional

PKCE methods — S256 only.

token_endpoint_auth_methods_supportedstring[]optional

Client authentication methods on /oauth/token.

revocation_endpoint_auth_methods_supportedstring[]optional

Client authentication methods on /oauth/revoke.

authorization_response_iss_parameter_supportedbooleanoptional

The authorization response carries iss (RFC 9207).

service_documentationstring (uri)optional

Link to the documentation. Present only if configured on the server.

{
  "issuer": "https://gateway.blyk.chat",
  "authorization_endpoint": "https://app.blyk.chat/oauth/authorize",
  "token_endpoint": "https://gateway.blyk.chat/oauth/token",
  "revocation_endpoint": "https://gateway.blyk.chat/oauth/revoke",
  "userinfo_endpoint": "https://gateway.blyk.chat/oauth/userinfo",
  "scopes_supported": [
    "profile"
  ],
  "response_types_supported": [
    "code"
  ],
  "response_modes_supported": [
    "query"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],
  "revocation_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "none"
  ],
  "authorization_response_iss_parameter_supported": true
}

OAuthError

object

Protocol error (RFC 6749 §5.2, RFC 6750 §3.1). No other fields.

errorOAuthErrorCoderequired

HTTP endpoint error code:

  • invalid_request — a required parameter is missing, a parameter is repeated, two authentication methods at once, wrong HTTP method;
  • invalid_client — the client was not recognised (401);
  • invalid_grant — the code or refresh token is not valid;
  • unsupported_grant_type — the grant_type is not supported;
  • invalid_scope — unknown scope or wider than granted;
  • invalid_token — the access token is not valid (401, /oauth/userinfo);
  • server_error — a failure on Blyk's side (500);
  • temporarily_unavailable — retry later (503).
invalid_requestinvalid_clientinvalid_grantunsupported_grant_typeinvalid_scopeinvalid_tokenserver_errortemporarily_unavailable
{
  "error": "invalid_grant"
}

OAuthErrorCode

string

HTTP endpoint error code:

  • invalid_request — a required parameter is missing, a parameter is repeated, two authentication methods at once, wrong HTTP method;
  • invalid_client — the client was not recognised (401);
  • invalid_grant — the code or refresh token is not valid;
  • unsupported_grant_type — the grant_type is not supported;
  • invalid_scope — unknown scope or wider than granted;
  • invalid_token — the access token is not valid (401, /oauth/userinfo);
  • server_error — a failure on Blyk's side (500);
  • temporarily_unavailable — retry later (503).
invalid_requestinvalid_clientinvalid_grantunsupported_grant_typeinvalid_scopeinvalid_tokenserver_errortemporarily_unavailable
"invalid_grant"

AuthorizeErrorCode

string

Error code in the redirect (RFC 6749 §4.1.2.1):

  • access_denied — the person pressed "Cancel";
  • invalid_request — no response_type, no PKCE from a public client, method other than S256, code_challenge not 43 base64url characters, code_challenge_method without code_challenge, state longer than 1024;
  • unsupported_response_type — response_type is not code;
  • invalid_scope — unknown scope.
access_deniedinvalid_requestunsupported_response_typeinvalid_scope
"access_denied"