.. Copyright (C) 2018-2024 SpaceKnow, Inc.

.. _api.user:

***********
User API
***********

User API provides an interface for user access administration. Back-end for
this API is an OIDC provider).

.. _Auth0: https://auth0.com/

* URL: https://api.spaceknow.com/user

.. _api.user.info:

Get User Info
=============

This API endpoint accepts a “Bearer” access token of a user. It returns
claims related to the user.

.. http:post:: /user/info

    **Example request**:

    .. sourcecode:: json

        {}


    :>json str id: unique OIDC ID of the user.
    :>json str email: user's e-mail.
    :>json str name: user's full name.
    :>json str accounting: name of user's accounting.
    :>json list permissions: list of permissions the user is granted. See
        :ref:`permission mechanics <api.mechanics.permissions>` for more
        information.

    **Example response**:

    .. sourcecode:: json

        {
            "id": "auth0|mGochhH3Pz5SiCWo8m44",
            "email": "john-smith@example.com",
            "name": "John Smith",
            "accounting": "development",
            "permissions": [
                "imagery.availability",
                "imagery.scene-info"
            ]
        }


Create Guardian User
====================

This API endpoint allows Guardian managers to create accounts.

**Needed Permissions**: ``admin.users.create-guardian-user``

.. http:post:: /user/guardian-user/create

    :>json str email: user's e-mail.
    :>json str password: user's initial password.
    :>json str name: user's full name.

    **Example request**:

    .. sourcecode:: json

        {
            "email": "john-smith@example.com",
            "password": "secret",
            "name": "John Smith"
        }

    **Example response**:

    .. sourcecode:: json

        {}

Delete Guardian User
====================

This API endpoint allows Guardian managers to delete accounts from their group.

**Needed Permissions**: ``admin.users.delete-guardian-user``

.. http:post:: /user/guardian-user/delete

    :>json str email: user's e-mail.

    **Example request**:

    .. sourcecode:: json

        {
            "email": "john-smith@example.com"
        }

    **Example response**:

    .. sourcecode:: json

        {}