Registering an application

There is no self-service instant registration. Two steps stand between a Nanako account and a working client_id: developer approval, then application creation.

1. Request developer access

Sign in at nanako.org, open the Developer app, and submit an application. You are asked for a reason — write at least 10 characters and no more than 500, and describe what you intend to build. A human reviews it.

You can hold only one application at a time. While one is pending you cannot submit another, and an already-approved account cannot re-apply.

Until you are approved, application creation is refused. Everything else on this page assumes approval has come through.

2. Create the application

From the same Developer page, create an application:

Field	Required	Rules
Name	Yes	2–100 characters
Description	No	Up to 500 characters
Homepage URL	No	Shown to users on the consent screen
Redirect URIs	Yes	At least one; each must start with http:// or https://
Scopes	No	Defaults to openid profile if you select none

Both the name and the description are shown to every user who is asked to authorize your app. Write them for that audience.

Redirect URI rules

The redirect URI is matched byte for byte against your registered list, both when the authorization request arrives and again when you exchange the code. There is no normalization: a trailing slash, a different case in the host, or an added parameter all make it a different URI.

Register every URI you will use — development and production — and send back exactly the string you registered.

Do not register a URI that already has a query string

The callback URL is assembled by appending ?code=…. A redirect URI that already contains ? produces a malformed callback and your client will not find the code parameter.

Register https://app.example.com/callback, not https://app.example.com/callback?source=nanako. Carry your own state in the state parameter instead.

Custom schemes such as myapp://callback are rejected at registration, so the RFC 8252 native-app pattern is not available yet.

3. Store the credentials

Creating the application returns your credentials:

{
  "app": {
    "client_id": "8f14e45fceea167a5a36dedd4bea2543",
    "name": "Example App",
    "redirect_uris": ["https://app.example.com/callback"],
    "scopes": ["profile", "email"]
  },
  "client_secret": "kZ8mQ2vX7pL4nR9tY6wA3sD1fG5hJ0cV8bN2mK4xQ7E="
}

client_id	32 lowercase hexadecimal characters. Public — it appears in browser URLs.
client_secret	44 characters of base64url ending in =. Shown once, never retrievable again.

Store the secret in your server's secret manager immediately. If you lose it, your only option is to regenerate — which invalidates the old one.

The = is part of the secret

The secret, the authorization code and both token types all end in a literal =. When you put any of them in a form-encoded request body, percent-encode it (%3D). Naive string concatenation silently truncates the value and you get invalid_client or invalid_grant with nothing to debug.

Every HTTP library does this for you if you pass the body as a parameter map rather than as a pre-built string.

Choosing scopes at registration

The scopes you select at registration become your application's permitted set. An authorization request for anything outside it is rejected with invalid_scope — the user never sees a consent screen.

The registration form offers profile, email and phone. It does not offer openid, and openid is the first scope in the default authorization request. So:

Always send an explicit scope

If you omit scope on the authorization request, Nanako defaults it to openid profile. An application registered through the web form does not have openid in its permitted set, so that default fails with:

{"error": "invalid_scope", "error_description": "scope 'openid' 不被允许"}

Send the scopes you actually registered, explicitly, on every request. See Scopes.

Managing the application

From the Developer page you can edit the name, description, redirect URIs and scopes at any time, regenerate the client secret, and delete the application.

Regenerating the secret takes effect immediately. Any server still holding the old secret starts receiving 401 invalid_client on the token endpoint — deploy the new one first, or accept a window of failed logins.

Deleting the application ends it for everyone: existing authorizations are withdrawn and users are no longer able to sign in through it.

Reviewing activity

Two read-only views help you confirm an integration is behaving:

• Authorized apps — which applications a user has approved, and the ability to revoke any of them.
• Authorization log — authorize, token and userinfo events with timestamp, IP, device type and outcome.

Both are in the Nanako account UI and both are per-user: you see your own activity, not your users'.

Note that only the first token exchange is logged. Silent refreshes over the following 30 days do not appear, so a quiet log does not mean an inactive integration.