apiary.apib

FORMAT: 1A
HOST: http://auth:3000/

# >_ secret_tech AUTH Service

Auth is a service that manages JWT-authentication, it's main responsibilities are:

1. Tenants management.
2. Users management.
3. Generation of JWT tokens.
4. Validation of JWT tokens.


Common workflow is following:

1. Register a tenant. Tenant is expected to be a service which requires authentication.
2. Login tenant. Save received token. Use this token further to manage your tenant's users. Make sure that your end users DO NOT have access to this token!
3. Create a user when he registers at your service.
4. Login the user when he logins at your service, save received token on user's side (Browser local storage, etc.).
5. Verify saved token whenever authentication required.
6. Logout the user when necessary.
7. Delete the user when his account is not active anymore or deleted.
8. Logout your tenant's session when you stop using your service or need to deactivate tenant token for some reason.

# Group Tenant

## Register tenant [/tenant]

### Register new tenant [POST]

+ email `test@test.com` (string, required, email)

+ password `passwordA6` (string, required, min: 6, regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{6,}$)

+ Request (application/json)

        {
            "email": "test@test.com",
            "password": "passwordA6"
        }

+ Response 200 (application/json)

        {
            "id": "0107bfcf-2f42-4e83-99e9-3ba44b737302",
            "email": "test@test.com",
            "token": "jwt_token"
        }

## Login tenant to create new JWT token [/tenant/login]

### Login tenant [POST]

+ email `test@test.com` (string, required, email)

+ password `passwordA6` (string, required, min: 6, regex: ^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d]{6,}$)

+ Request (application/json)

        {
            "email": "test@test.com",
            "password": "password"
        }

+ Response 200 (application/json)

        {
            "token": "jwt_token"
        }

## Logout tenant to invalidate JWT token [/tenant/logout]

### Logout tenant [POST]

+ accessToken `jwt` (string, required)

+ Request (application/json)

        {
            "token": "jwt_token"
        }

+ Response 200 (application/json)

        {
            "result": 1
        }

## Verify tenant's JWT token [/tenant/verify]

### Verify tenant's token [POST]

+ token `jwt` (string, required)

+ Request (application/json)

        {
            "token": "jwt_token"
        }

+ Response 200 (application/json)

        {
            "decoded": {
                "id": "24d22df4-5709-4506-a974-646d78b519fb",
                "login": "tenant:companies@jincor.com",
                "jti": "24d22df4-5709-4506-a974-646d78b519fb1505744965000",
                "iat": 1505744965000,
                "aud": "jincor.com",
                "isTenant": true
            }
        }

+ Response 400 (application/json)

        {
            "error": "invalid token"
        }

# Group User

## Create user [/user]

**Important note:**
"Scope" field is used to store user permissions.
It might be either just a string containing user role (e.g. "company-admin")
or an object describing what operations user can perform with resources (e.g. {
    "company": [
        "create",
        "read",
        "update",
        "delete"
    ],
    "employee": [
        "read"
    ]
})


###  Create new user [POST]

+ email `test@test.com` (string, required, email)

+ login `test@test.com` (string, required)

+ password `passwordA6` (string, required)

+ sub `Application specific subject, e.g. some ID in 3rd party service` (string, required)

+ scope `scope` (optional)

+ Request (application/json)

        {
            "login": "test_gmail.com",
            "email": "test@gmail.com",
            "password": "passw0Rd",
            "sub": "test"
        }

+ Response 200 (application/json)

        {
            "id": "0107bfcf-2f42-4e83-99e9-3ba44b737302",
            "login": "testuser",
            "email": "test@test.com",
            "tenant": "0107bfcf-2f42-4e83-99e9-3ba44b737302",
            "scope": "user_scope",
            "registrationDate": 1542384291572,
            "lastActivity": 1542384471740
        }



## List users [/user{?q}{?cursor}]

In case pagination requested the first value in response is always `cursor`. If you need to load the next page, provide cursor 
in the next request parameter to load the next page. "0" is always for the first page if you see "0" in respone - there is no
next page. It doesnt apply if  you search for users. Pagination for search requests is not supported

###  List users for tenant [GET]

+ Parameters

    + q (string, optional)
      query string to search users by login
    + cursor (string, optional)
      cursor for pagination

+ Response 200 (application/json)

        [
            {
                "id": "0107bfcf-2f42-4e83-99e9-3ba44b737302",
                "login": "testuser",
                "email": "test@test.com",
                "scope": "advisor",
                "tenant": "c3a1e8d6-c361-4d55-8f26-e5134d804556",
                "sub": "facebookId",
                "registrationDate": 1542384291572,
                "lastActivity": 1542384471740
            },
            {
                "id": "0107bfcf-2f42-4e83-99e9-3ba44b737302",
                "login": "testuser",
                "email": "test@test.com",
                "scope": "advisor",
                "tenant": "c3a1e8d6-c361-4d55-8f26-e5134d804556",
                "sub": "facebookId",
                "registrationDate": 1542384291572,
                "lastActivity": 1542384471740
            }
        ]

+ Response 200 (application/json)

        [
            "0",
            {
                "id": "0107bfcf-2f42-4e83-99e9-3ba44b737302",
                "login": "testuser",
                "email": "test@test.com",
                "tenant": "c3a1e8d6-c361-4d55-8f26-e5134d804556",
                "scope": "advisor",
                "sub": "facebookId",
                "registrationDate": 1542384291572,
                "lastActivity": 1542384471740
            },
            {
                "id": "0107bfcf-2f42-4e83-99e9-3ba44b737302",
                "login": "testuser",
                "email": "test@test.com",
                "tenant": "c3a1e8d6-c361-4d55-8f26-e5134d804556",
                "scope": "advisor",
                "sub": "facebookId",
                "registrationDate": 1542384291572,
                "lastActivity": 1542384471740
            }
        ]

## Delete user [/user/{login}]

###  Delete a user [DELETE]

+ Response 200 (application/json)

        {
            "result": 1
        }

+ Response 404 (application/json)

        {
            "error": "Specified login does not exist or was already deleted."
        }

# Group Auth

## Login a user [/auth]

### Login [POST]

+ login `login` (string, required)

+ password `passwordA6` (string, required)

+ deviceId `someId` (string, required)

+ Request (application/json)

        {
            "login": "user_login",
            "password": "password_hash",
            "deviceId": "id"
        }

+ Response 200 (application/json)

        {
            "accessToken": "jwt_token"
        }

+ Response 403 (application/json)

        {
            "error": "Incorrect password",
            "status": 403
        }

+ Response 404 (application/json)

        {
            "error": "User does not exist",
            "status": 404
        }

+ Response 422 (application/json)

        {
            "error": {
                "isJoi": true,
                "name": "ValidationError",
                "details": [
                    {
                        "message": "\"password\" length must be at least 6 characters long",
                        "path": "password",
                        "type": "string.min",
                        "context": {
                            "limit": 6,
                            "value": "test6",
                            "key": "password"
                        }
                    }
                ],
                "_object": {
                    "email": "companies@jincor",
                    "password": "test6"
                }
            },
            "value": {
                "email": "companies@jincor",
                "password": "test6"
            }
        }

## Verify token [/auth/verify]

### Verify [POST]

+ token `token` (string, required)

+ Request (application/json)

        {
            "token": "jwt_token"
        }

+ Response 200 (application/json)

        {
            "decoded": {
                "id": "0107bfcf-2f42-4e83-99e9-3ba44b737302",
                "login": "tenant_id:test@test.com",
                "scope": "user_scope",
                "deviceId": "12345",
                "jti": "0107bfcf-2f42-4e83-99e9-3ba44b737302123451498632187982",
                "iat": 1498632187982,
                "exp": 1498632792782
            }
        }

+ Response 400 (application/json)

        {
            "error": "invalid token"
        }

## Logout [/auth/logout]

### Logout [POST]

+ token `token` (string, required)

+ Request (application/json)

        {
            "token": "jwt_token"
        }

+ Response 200 (application/json)

        {
            "result": 1
        }

+ Response 400 (application/json)

        {
            "error": "invalid token"
        }