Unicat API Reference

Up - API Reference - Home

/api/login

Note: Use this only if you're making some app and you want to allow a user to login. For usage of the API, use your API key and continue at the /api/p/<project gid>/auth endpoint.

Provide credentials, get a JWT and initial user and projects data. The JWT is used in subsequent requests that require authorization. The initial data is a convenience that you can also get from the /api/init call.

Any subsequent request that uses the JWT can auto-refresh it if it's not expired. If that happens, you'll get a new Authorization header in the response with the renewed JWT, and you should use that one from then on.

Request

POST /api/login

{
    "username": "<your-username-here>",
    "password": "<your-password-here>"
}

Success response

Authorization: <JWT>

{
    "success": true,
    "result": {
        "user": "<user gid>",
        "user_projects": {
            "<project gid>": [
                "owner"
            ],
            …
        },
        "cc.version": "2022.01.001",
        "cc.cursor": 4132,
    },
    "data": {
        "cc.users": {
            "<user gid>": {
                "gid": "<user gid>",
                "username": "user-name",
                "email": "<user email>",
                "name": "User Name",
                "avatar": "1ad71cbd-9b97-4ea7-94ef-bcdd86c6467c.jpg",
                "status": "active",
                "options": {
                    "language": "en",
                    "timezone": "Europe/Amsterdam"
                }
            }
        },
        "cc.projects": {
            "<project gid>": {
                "gid": "<project gid>",
                "name": "Project Name",
                "icon": "<project gid>.jpg",
                "owner": "<user gid>",
                "status": "active"
            },
            …
        },
        "cc.projects_members": [
            {
                "project_gid": "<project gid>",
                "user_gid": "<user gid>",
                "status": "active",
                "roles": [
                    "owner"
                ],
                "options": {
                    "notifications": {
                        "email": "<user email>",
                        "events": [
                            "all"
                        ],
                        "frequency": "immediate"
                    },
                    "rate_limit_per_second": null
                }
            },
            …
        ],
        "cc.languages": {
            "da": "Danish",
            "nl": "Dutch",
            …
        },
    }
}

The JWT you need is in the Authorization header.

result

user is the user gid if the login is successful.
user_projects is a dictionary of zero or more projects that are owned by this user or the user is a member of.
cc.version is the current version.
cc.cursor a sync cursor, to keep cc-data in sync.

data

cc.users is a dictionary with entries for the current user and members of a user's projects.
cc.projects is a dictionary with metadata for each project.
cc.projects_members is a list with metadata for project-owner membership.
cc.languages available languages for internationalization and localization.

Error response

400 Bad request - missing parameters (only the first is reported)
403 Forbidden - unknown user or wrong password

HTTP/1.1 400 Bad request

{
    "success": false,
    "result": {
        "code": 400,
        "message": "Bad request",
        "info": {
            "Missing parameter": "name"
        }
    },
    "data": {}
}

HTTP/1.1 403 Forbidden

{
    "success": false,
    "result": {
        "code": 403,
        "message": "Unknown user",
        "info": {}
    },
    "data": {}
}