>_ secret_tech AUTH Service

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

Tenants management.
Users management.
Generation of JWT tokens.
Validation of JWT tokens.

Common workflow is following:

Register a tenant. Tenant is expected to be a service which requires authentication.
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!
Create a user when he registers at your service.
Login the user when he logins at your service, save received token on user’s side (Browser local storage, etc.).
Verify saved token whenever authentication required.
Logout the user when necessary.
Delete the user when his account is not active anymore or deleted.
Logout your tenant’s session when you stop using your service or need to deactivate tenant token for some reason.

Tenant ¶

Register tenant ¶

Register new tenant
POST`/tenant`

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

Example URI

POST http://auth:3000//tenant

Request

HideShow

Headers

Content-Type: application/json

Body

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

Response 200

HideShow

Headers

Content-Type: application/json

Body

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

Login tenant to create new JWT token ¶

Login tenant
POST`/tenant/login`

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

Example URI

POST http://auth:3000//tenant/login

Request

HideShow

Headers

Content-Type: application/json

Body

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

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "token": "jwt_token"
}

Logout tenant to invalidate JWT token ¶

Logout tenant
POST`/tenant/logout`

accessToken jwt (string, required)

Example URI

POST http://auth:3000//tenant/logout

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "token": "jwt_token"
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "result": 1
}

Verify tenant's JWT token ¶

Verify tenant's token
POST`/tenant/verify`

token jwt (string, required)

Example URI

POST http://auth:3000//tenant/verify

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "token": "jwt_token"
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

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

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "invalid token"
}

User ¶

Create 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`/user`

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)

Example URI

POST http://auth:3000//user

Request

HideShow

Headers

Content-Type: application/json

Body

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

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "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 ¶

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`/user{?q}{?cursor}`

Example URI

GET http://auth:3000//user?q=?cursor=

URI Parameters

HideShow

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

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "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

HideShow

Headers

Content-Type: application/json

Body

[
  "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 ¶

Delete a user
DELETE`/user/`

Example URI

DELETE http://auth:3000//user/

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "result": 1
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

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

Auth ¶

Login a user ¶

Login
POST`/auth`

login login (string, required)
password passwordA6 (string, required)
deviceId someId (string, required)

Example URI

POST http://auth:3000//auth

Request

HideShow

Headers

Content-Type: application/json

Body

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

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "accessToken": "jwt_token"
}

Response 403

HideShow

Headers

Content-Type: application/json

Body

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

Response 404

HideShow

Headers

Content-Type: application/json

Body

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

Response 422

HideShow

Headers

Content-Type: application/json

Body

{
  "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 ¶

Verify
POST`/auth/verify`

token token (string, required)

Example URI

POST http://auth:3000//auth/verify

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "token": "jwt_token"
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

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

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "invalid token"
}

Logout ¶

Logout
POST`/auth/logout`

token token (string, required)

Example URI

POST http://auth:3000//auth/logout

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "token": "jwt_token"
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "result": 1
}

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "error": "invalid token"
}

Tenant ¶

Register tenant ¶

Register new tenantPOST/tenant

Example URI

Headers

Body

Headers

Body

Login tenant to create new JWT token ¶

Login tenantPOST/tenant/login

Example URI

Headers

Body

Headers

Body

Logout tenant to invalidate JWT token ¶

Logout tenantPOST/tenant/logout

Example URI

Headers

Body

Headers

Body

Verify tenant's JWT token ¶

Verify tenant's tokenPOST/tenant/verify

Example URI

Headers

Body

Headers

Body

Headers

Body

User ¶

Create user ¶

Create new userPOST/user

Example URI

Headers

Body

Headers

Body

List users ¶

List users for tenantGET/user{?q}{?cursor}

Example URI

Headers

Body

Headers

Body

Delete user ¶

Delete a userDELETE/user/

Example URI

Headers

Body

Headers

Body

Auth ¶

Login a user ¶

LoginPOST/auth

Example URI

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Verify token ¶

VerifyPOST/auth/verify

Example URI

Headers

Body

Headers

Body

Headers

Body

Logout ¶

LogoutPOST/auth/logout

Example URI

Headers

Register new tenant
POST`/tenant`

Login tenant
POST`/tenant/login`

Logout tenant
POST`/tenant/logout`

Verify tenant's token
POST`/tenant/verify`

Create new user
POST`/user`

List users for tenant
GET`/user{?q}{?cursor}`

Delete a user
DELETE`/user/`

Login
POST`/auth`

Verify
POST`/auth/verify`

Logout
POST`/auth/logout`