Unicat API Reference

Up - API Reference - Home

/api/p/<project gid>/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 with the auth endpoint.

Provide credentials, get a JWT and initial user and projects data, and initial data for the current project. The JWT is used in subsequent requests that require authorization. The initial data is a convenience that you can also get from the /api/p/<project gid>/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.

Making this call to the project api will give you specific initial data for that project and its members - but only if the user is actually a member or the owner of the project.

Request

POST /api/p/<project gid>/login

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

Success response

Authorization: <JWT>

{
    "success": true,
    "result": {
        "user": "<user gid>",
        "user_projects": {
            "<project gid>": [
                "owner"
            ],
            …
        },
        "project": "<project gid>",
        "project_members": ["<user gid>", "<member user gid>", …],
        "last_backed_up": 1612184925.9805226,
        "cc.version": "2022.01.001",
        "cc.cursor": 4132,
        "cursor": 7864,
    },
    "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"
                }
            },
            "<member user gid>": {
                "gid": "<member user gid>",
                "username": "member-name",
                "name": "Member Name",
                "avatar": "f2e64fe0-9ffa-4d9a-8750-d561d6542453.png",
                "status": "active"
            },
            …
        },
        "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
                }
            },
            {
                "project_gid": "<project gid>",
                "user_gid": "<member user gid>",
                "status": "active",
                "roles": [
                    "member"
                ]
            },
            …
        ],
        "definitions": {…},
        "classes": {…},
        "fields": {…},
        "layouts": {…},
        "queries": {…},
    }
}

The JWT you need is in the Authorization header.

result

user is the user gid if the login is successful.
user_projects is a list of zero or more projects that are owned by this user.
project is the project gid if the user is a member of the project. If not, this value will be null, but the login is still valid.
project_members is a list of project members gids (these are user gids).
last_backed_up is a server-side timestamp for the last backup of the database, or null if it was never backed up.
cc.version is the current version.
cc.cursor a sync cursor, to keep cc-data in sync.
cursor a sync cursor, to keep project-data in sync.

data

cc.users is a dictionary with a full entry for the current user, and reduced metadata for all the other members.
cc.projects is a dictionary with a full entry for the current project, and reduced metadata for each other owned project.
cc.projects_members is a list with metadata for all project-member relations.

definitions is a dictionary holding all definitions for the project.
classes is a dictionary holding all classes for the project.
fields is a dictionary holding all fields for the project.
layouts is a dictionary holding all layouts for the project. queries is a dictionary holding all queries for the project.

Error response

Note: You cannot login successfully on this URL if you're not a member of this project.

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": {}
}