Public & Basic-auth User APIs

Endpoints for looking up users, a user’s organizations, social follow relationships, managing a user’s access tokens over HTTP Basic auth, and public sign-in. All paths on this page are relative to the API root /api/v1 (for example, /users/search is https://<akp-host>/api/v1/users/search).

Authentication varies per endpoint:

• Public — no credentials required.
• Basic auth — HTTP Basic authentication (username + password), used by the token-management endpoints. A 2FA one-time-password header may also be required.
• Token — a personal access token (Authorization: token <YOUR_TOKEN>), used by the follow-relationship endpoints.

User lookup

GET /users/search

Search for users by keyword or user ID.

• Auth: Public.

Query parameters:

Response: 200 OK — a wrapper with an ok flag and a data array of users.

{
  "ok": true,
  "data": [
    {
      "id": 4,
      "login": "someuser",
      "username": "someuser",
      "full_name": "Some User",
      "email": "[email protected]",
      "avatar_url": "https://secure.gravatar.com/avatar/<hash>?d=identicon",
      "type": 0,
      "active": true,
      "is_admin": false
    }
  ]
}

Verified: GET /users/search?q=a&limit=2 returned 200 against appscode on 2026-07-14.

Example:

curl -H "Authorization: token $AKP_TOKEN" \
  "https://<akp-host>/api/v1/users/search?q=alice&limit=10"

(The token is optional here since the endpoint is public.)

GET /users/{username}

Get the public profile of a single user by username.

• Auth: Public.

Path parameters:

Response: 200 OK — a User object; 404 if no such user.

{
  "id": 2,
  "login": "someuser",
  "username": "someuser",
  "full_name": "Some User",
  "email": "[email protected]",
  "avatar_url": "https://secure.gravatar.com/avatar/<hash>?d=identicon",
  "language": "en-US",
  "is_admin": false,
  "type": 0,
  "active": true
}

Verified: GET /users/appscode returned 200 against appscode on 2026-07-14.

GET /users/{username}/orgs

List the organizations a user belongs to.

• Auth: Public.

Path parameters:

Response: 200 OK — an array of Organization objects.

[
  {
    "id": 1,
    "username": "appscode",
    "full_name": "AppsCode Inc.",
    "avatar_url": "https://secure.gravatar.com/avatar/<hash>?d=identicon",
    "description": "",
    "website": "",
    "location": "",
    "visibility": "public",
    "orgType": 1
  }
]

Verified: GET /users/appscode/orgs returned 200 against appscode on 2026-07-14.

Social follow (public/token)

GET /users/{username}/followers

List a user’s followers.

• Auth: Token.

Path parameters:

Query parameters:

Response: 200 OK — an array of User objects.

Verified: GET /users/appscode/followers returned 200 against appscode on 2026-07-14.

GET /users/{username}/following

List the users a given user follows.

• Auth: Token.

Path parameters:

Query parameters:

Response: 200 OK — an array of User objects.

Verified: GET /users/appscode/following returned 200 against appscode on 2026-07-14.

GET /users/{username}/following/{target}

Check whether one user follows another.

• Auth: Token.

Path parameters:

Response: 204 No Content if username follows target; 404 otherwise.

Access tokens over HTTP Basic auth

These endpoints manage a user’s personal access tokens using HTTP Basic authentication. Tokens always belong to the authenticated user.

GET /users/{username}/tokens

List a user’s access tokens.

• Auth: Basic auth. A 2FA OTP header may also be required if the account has 2FA enabled.

Path parameters:

Response: 200 OK — an array of AccessToken objects. Note that sha1 (the plaintext token) is only ever populated on creation.

[
  {
    "id": 12,
    "name": "ci-token",
    "token_last_eight": "1a2b3c4d"
  }
]

POST /users/{username}/tokens

Create an access token for the authenticated user.

• Auth: Basic auth.

Path parameters:

Request body: CreateAccessTokenOption.

{
  "name": "ci-token"
}

Response: 201 Created — the created AccessToken. The plaintext token is returned in sha1 only on this response — store it now, it cannot be retrieved later.

{
  "id": 13,
  "name": "ci-token",
  "sha1": "<plaintext-token>",
  "token_last_eight": "9f8e7d6c"
}

DELETE /users/{username}/tokens/{id}

Delete one of the authenticated user’s access tokens.

• Auth: Basic auth.

Path parameters:

Response: 204 No Content.

Sign in

POST /user/signin

Public sign-in with username and password.

• Auth: Public. On success, session/CSRF/NATS cookies are set. Accounts enrolled in 2FA cannot sign in through this endpoint (returns 405).

Request body: SignInParams.

{
  "username": "someuser",
  "password": "<password>",
  "remember": true
}

Response: 200 OK with no body (session cookies set). Other statuses: 404 user does not exist, 405 login prohibited / user inactive / 2FA enabled, 409 email already in use, 422 validation error.

Object reference

User object

Organization object

AccessToken object