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".
Quick Start
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.
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.
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.
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
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
| Parameter | Description |
|---|---|
| code | The authorization code from the previous step |
| client_id | appId |
| client_secret | appSecret |
| redirect_uri | Callback URL matching the one used for authorization |
Response
{
"ok": true,
"access_token": "f0c4...",
"token_type": "Bearer",
"expires_in": 600
}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
| HTTP | Error | Description |
|---|---|---|
| 401 | missing_token / invalid_token | Missing or invalid access_token |
| 401 | invalid_client | Incorrect appId / appSecret |
| 400 | invalid_grant | The authorization code is invalid, expired, or already used |
| 400 | redirect_mismatch | Callback URL does not match the registered value (hijack protection) |
| 400 | unknown_client | The app does not exist or has been disabled |
| 429 | Too 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_urimust 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.