"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.
- Open the "You" ("Вы") → "Development" ("Разработка") → "My apps"
("Мои приложения") tab and press "Create app" ("Создать
приложение").
- 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.
- 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.
- 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.
- 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
- 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.
- 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.
- 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.
- 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".
- Check
state (matches the stored one) and iss (equals
https://gateway.blyk.chat). On mismatch, abort.
- 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.
- 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.
- 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.
- 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.