Cocode Open Platform

Add Cocode sign-in to your software in minutes · OAuth 2.0 Authorization Code flow

Overview

The Cocode Open Platform uses the OAuth 2.0 Authorization Code flow so third-party software can authenticate users through the Cocode unified account system. Once a user grants access, your app receives an access_token and can read that user's nickname and avatar.

Built for desktop apps, mini programs, and any software that wants to offer "Sign in with Cocode".

Authorization Code flow: tokens are exchanged on the backend, so appSecret never leaves your server and is never exposed to the client.

Quick Start

1

Sign up and request developer access

Create an account on our website and activate it, then contact an administrator to grant you the developer role.

2

Create an app

Open the Developer Center and enter an app name and callback URL (redirect_uri). When the app is created, you get its appId and appSecret — shown only once.

3

Wire up authorization

Call the Get an Authorization URL endpoint from your software, then open the returned URL in the system browser. The user signs in, grants access, and is redirected back automatically.

4

Exchange for a token

When your callback receives the code, exchange code + appId + appSecret for an access_token, then use it to query user info.

Authorization Flow

Your app                            Cocode Account Center          User
   │  1. Call /api/authorize-url.php        │                          │
   │───────────────────────────────────────▶│                          │
   │  2. Return the authorization URL       │                          │
   │◀───────────────────────────────────────│                          │
   │  3. Open the URL in the system browser ──▶ Sign in + approve      │
   │                                        │◀────────────────────────▶│
   │  4. Redirect back with code + state    │                          │
   │◀───────────────────────────────────────│                          │
   │  5. Call /api/token.php                │  code + appSecret        │
   │───────────────────────────────────────▶│                          │
   │  6. Return access_token                │                          │
   │◀───────────────────────────────────────│                          │
   │  7. Call /api/userinfo.php             │  access_token            │
   │───────────────────────────────────────▶│                          │
   │  8. Return user info                   │                          │
   │◀───────────────────────────────────────│                          │

Client Integration Example

In Electron, C#, or any desktop app, it comes down to three steps: get an authorization URL, open it in the system browser, and catch the code on a local callback to exchange for a token.

JavaScript (Electron / browser)

// 1. Get the authorization URL (browsers can use native fetch; in Node/Electron without fetch, use axios or similar)
const resp = await fetch(
  'https://kuma9.com/api/authorize-url.php' +
  '?client_id=' + encodeURIComponent(APP_ID) +
  '&redirect_uri=' + encodeURIComponent(REDIRECT_URI) +
  '&state=' + state
);
const { authorize_url } = await resp.json();

// 2. Open the authorization page in the system browser (after sign-in and approval the browser returns to RETDIRECT_URI?code=...&state=...)
require('child_process').exec('start "" "' + authorize_url + '"');   // Windows
// macOS / Linux: open or xdg-open

// 3. Once the local callback server receives the code, exchange it for an access_token on the backend
const token = await fetch('https://kuma9.com/api/token.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: 'code=' + encodeURIComponent(code) +
        '&client_id=' + encodeURIComponent(APP_ID) +
        '&client_secret=' + encodeURIComponent(APP_SECRET) +
        '&redirect_uri=' + encodeURIComponent(REDIRECT_URI)
}).then(r => r.json());

// 4. Query the user with the access_token
const me = await fetch('https://kuma9.com/api/userinfo.php', {
  headers: { 'Authorization': 'Bearer ' + token.access_token }
}).then(r => r.json());
console.log(me.user.nickname);

The usual approach for desktop apps: start a local HTTP server on http://127.0.0.1:PORT/callback and register that address as the app callback. After authorization the browser is sent there, your local server captures the code, closes the browser window, completes the token exchange, and stores the session.

Endpoints

GET/api/authorize-url.php

Validates the app and returns an authorization URL you can open (the client entry point)

GET/account/authorize

Authorization consent page (opened in the browser); redirects back once the user approves

POST/api/token.php

Exchanges the authorization code for an access_token

GET/api/userinfo.php

Returns the current user's info using an access_token

6. Get an Authorization URL

First step on the client: call this endpoint to get an authorization URL you can hand straight to the system browser.

GET/api/authorize-url.php

ParameterTypeRequiredDescription
client_idstringYesYour appId
redirect_uristringYesCallback URL; must match the registered value exactly
statestringNoRandom string to prevent CSRF; returned unchanged on redirect — always verify it

Response

{
  "ok": true,
  "authorize_url": "https://kuma9.com/account/authorize?client_id=capp_xxx&redirect_uri=https%3A%2F%2F...&state=abc",
  "client": "My App"
}

If client_id is invalid or redirect_uri does not match the registered value, the API returns ok:false with a 400 error.

7. Exchange for an access_token

After the user approves, the browser redirects back to your callback URL with a code (and state). Your software sends that code to your backend to exchange for a token.

POST/api/token.php

ParameterDescription
codeThe authorization code from the previous step
client_idappId
client_secretappSecret
redirect_uriCallback URL matching the one used for authorization

Response

{
  "ok": true,
  "access_token": "f0c4...",
  "token_type": "Bearer",
  "expires_in": 600
}
The authorization code is single-use and time-limited, and token exchange must happen on the backend. Never put appSecret in client code or on the front end.

8. Get User Info

GET/api/userinfo.php

Authentication: the Authorization: Bearer <access_token> request header, or the ?access_token=... URL parameter

Response

{
  "ok": true,
  "user": {
    "id": 12,
    "email": "user@example.com",
    "nickname": "Cody",
    "avatar": "/uploads/avatars/xxxx.png"
  }
}

9. Error Codes

HTTPErrorDescription
401missing_token / invalid_tokenMissing or invalid access_token
401invalid_clientIncorrect appId / appSecret
400invalid_grantThe authorization code is invalid, expired, or already used
400redirect_mismatchCallback URL does not match the registered value (hijack protection)
400unknown_clientThe app does not exist or has been disabled
429Too many requests.Rate limit reached; please try again later

10. Security Best Practices

  • state parameter: generate a random string and compare it on redirect to prevent cross-site request forgery.
  • Callback URL: https is required in production, and redirect_uri must match the registered value exactly.
  • appSecret: keep it on the backend only — never in client or front-end code. If it leaks, reset it in the Developer Center immediately.
  • access_token: tokens expire, so store them carefully. If one leaks, reset the app secret to invalidate them all.
  • Authorization code: single-use — never reuse or cache it.

11. FAQ

Q: What callback URL should a desktop app use?

A: Start a local callback server inside your app (for example, http://127.0.0.1:18000/callback) and enter that address in your app settings. After authorization the browser visits it with the code; your local server captures the code and can then continue with the token exchange.

Q: Why am I seeing "redirect_mismatch"?

A: The redirect_uri you send is not exactly the same as the value registered in the console (including http/https, port, and trailing slash). Compare them character by character.

Q: What if I lose my appSecret?

A: In the Developer Center, click "Reset secret". The old secret is invalidated immediately and a new one is generated.

Q: How long is the authorization code valid? And the token?

A: The authorization code is valid for 10 minutes and can be used once; the access_token lasts 10 minutes by default, after which the user must authorize again.

Add Cocode sign-in to your software

Free · integrate in just a few minutes.

Open Developer CenterContact Us