NEOK / IDENTITY

Sign in with NEOK

NEOK Identity lets applications authenticate users with their NEOK Account using OAuth 2.0 Authorization Code + UserInfo with PKCE. This is not full OpenID Connect: ID tokens and JWKS are not supported.

Get a NEOK Account ↗Developer overview

01 / OVERVIEW

One identity, many applications.

Use the authorization-code flow to connect a local application account to the immutable NEOK user identity. Keep application sessions and authorization state on your server.

Discovery

https://neok.me/.well-known/oauth-authorization-server

Flow

Authorization Code + PKCE S256

02 / ENDPOINTS

Provider endpoints

Authorization: GET https://neok.me/identity/authorize
Token: POST https://neok.me/api/v1/identity/token
UserInfo: GET https://neok.me/api/v1/identity/userinfo
Discovery: GET https://neok.me/.well-known/oauth-authorization-server

03 / AUTHORIZATION

Start an authorization request.

Send these parameters to the authorization endpoint. Generate state and the PKCE verifier/challenge with a cryptographically secure random source, and keep the verifier server-side.

GET https://neok.me/identity/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example%2Fauth%2Fcallback
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_S256_CHALLENGE
  &code_challenge_method=S256
  &scope=openid%20profile%20email

The user signs in to NEOK and, where required, approves the requested scopes. The registered callback receives a short-lived one-time code and the original state.

04 / TOKEN EXCHANGE

Exchange the code server-side.

POST form-encoded fields to the token endpoint using client_secret_post for confidential clients or none for public clients. HTTP Basic authentication and query-string credentials are not supported. PKCE uses S256 with a 43–128 character unreserved verifier. Never send secrets in URLs.

grant_type=authorization_code
code=AUTHORIZATION_CODE
redirect_uri=https%3A%2F%2Fapp.example%2Fauth%2Fcallback
client_id=YOUR_CLIENT_ID
code_verifier=ORIGINAL_PKCE_VERIFIER
client_secret=SERVER_ONLY_SECRET

05 / USERINFO

Map accounts by canonical identity.

sub and neok_user_uuid identify the same immutable NEOK Account UUID. Do not use email as a permanent account key or silently merge local accounts by email.

{
  "sub": "uuid",
  "neok_user_uuid": "uuid",
  "name": "Example User",
  "email": "user@example.com",
  "email_verified": true
}

06 / SCOPES

openid

Returns sub and neok_user_uuid.

profile

Returns the user's display name.

email

Returns email and email_verified.

NEOK Identity does not expose purchases, subscriptions, licenses, entitlements, or internal administration roles through these scopes.

07 / CLIENT TYPES

Choose the right client boundary.

Public client

PKCE S256 is required. No client secret is used. Suitable for browser and mobile applications.

Confidential client

Keep the client secret server-side. Use PKCE as well, and never ship the secret in frontend or mobile code.

08 / REDIRECTS

Register exact callback URLs.

Exact match only; no wildcards.
HTTPS is required, except localhost development callbacks.
The registered URI must match both authorization and token requests.

09 / SECURITY

Keep the protocol boundary secure.

Use a required, one-time state value and validate it on callback.

Use PKCE S256 for public clients and confidential clients.

Authorization codes are short-lived and one-time use.

Exchange tokens server-side for confidential clients.

Never log tokens, secrets, authorization codes, or verifiers.

Reject inactive or unverified identities and validate the canonical UUID.

10 / ERRORS

Safe, predictable failures.

Common errors include invalid_request, invalid_client, invalid_redirect_uri, invalid_grant, invalid_scope, and access_denied. Applications should show a generic recovery message and never expose internal stack traces.

11 / INTEGRATION FLOW

Your app

→

NEOK authorize

→

Callback code

→

Token → UserInfo

12 / QUICK START

Server-side integration.

Laravel / PHP

$state = Str::random(40);
$verifier = Str::random(64);
$challenge = rtrim(strtr(base64_encode(hash('sha256', $verifier, true)), '+/', '-_'), '=');
// Store $state and $verifier in the server session.
// Redirect to the authorization endpoint with the values above.

Generic server-side app

1. Generate and store state plus a PKCE verifier.
2. Redirect to NEOK with the exact registered callback and S256 challenge.
3. Validate state, then exchange the one-time code server-side.
4. Call UserInfo and map the local account by neok_user_uuid.

Ready to connect an application?

Developer application registration remains restricted pending security review.

Get a NEOK Account ↗Manage existing applications