GuwinUS Identity API reference

Authentication

Send an API key in the HTTP Authorization header. Keys begin with gwk_. GuwinUS stores only a SHA-256 hash, so a lost key must be replaced.

Authorization: Bearer gwk_YOUR_KEY

Response format

{"ok":true,"data":{...}}

{"ok":false,"error":{"code":"invalid_token","message":"..."}}

Use HTTP status codes first, then the machine-readable error.code.

Scopes

GET /me

Returns the API-key owner and granted scopes. Requires profile.read.

curl https://identity.guwin.us/api/v1/me \
 -H "Authorization: Bearer gwk_YOUR_KEY"

Organizations

GET /organizations lists accessible organizations. POST /organizations creates one. Organization-specific routes support details, members, roles, and domains.

POST /api/v1/organizations
{"name":"Acme","slug":"acme","description":"Acme team"}

POST /api/v1/organizations/{id}/members
{"email":"[email protected]","role":"member"}

Application profiles

Application profiles let an app enrich a GuwinUS identity without changing the universal core account. Profiles are JSON namespaced by your appKey.

PUT /api/v1/users/{userId}/profiles/crm
{"jobTitle":"Director","customerTier":"gold"}

OAuth applications

GET /applications lists clients. POST /applications creates a client and returns a confidential secret once when applicable.

POST /api/v1/applications
{"name":"My App","client_type":"confidential","redirect_uri":"https://app.example/callback"}

ID card resolve

POST /id-card/resolve requires idcard.scan. Send an opaque gwi_… card code. The response includes only fields the card owner currently shares.

Versioning

Breaking REST changes will use a new major path. Existing /api/v1 integrations should not require silent breaking changes.