Back to top

Urjanet AuthServer API

Last modified: 2015-10-25

AuthServer is a centralized authentication and authorization server. By logging in via this server, you will receive a Bearer Token, which you can use to authenticate yourself with any other participating services at Urjanet.

AuthServer must be connected to over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

Authentication

Authentication action

Log in
POST/api/login

You can log in using this action. It takes a JSON object containing your username and a password.

  • username (string) - Your username

  • password (string) - Your password

  • scope (enum, optional) - The scope of the request

    • Members

      • ANY - The default
      • OFFLINE - Allow the token to be refreshed

Example URI

POST https://auth.urjanet.net/api/login
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "username": "some-user",
  "password": "some-password",
  "scope": "OFFLINE"
}
Response  200
HideShow

If your login is successful you will receive the following response.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "expires": "1443742827",
  "message": "Authentication Successful",
  "status": 200,
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJkZjUzMDViFX1BEUlwiXX0ifQ.qeJ63BD-VVDwL5xiK-wqFzdrTKH",
  "refreshToken": "B6970AAD-2E32-4BA3-A876-EEA60E57CC56",
  "type": "Bearer"
}
Schema
{
  "type": "object",
  "properties": {
    "expires": {
      "type": "number",
      "description": "The time this token will expire (expressed in seconds since January 1, 1970)."
    },
    "message": {
      "type": "string",
      "description": "A human-readable description of the response."
    },
    "status": {
      "type": "number",
      "description": "The HTTP status code"
    },
    "token": {
      "type": "string",
      "description": "The bearer token"
    },
    "refreshToken": {
      "type": "string",
      "description": "The refresh token"
    },
    "type": {
      "type": "string",
      "description": "The type of token returned in the response"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  401
HideShow

If your login is unsuccessful you will receive the following response. This can happen for a number of reasons, including:

  • The credentials you provided are incorrect

  • Your account has been locked

  • Your account has expired

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "error": "Unauthorized",
  "message": "Authentication Failed: Bad credentials",
  "path": "/api/login",
  "status": 401,
  "timestamp": 1443749329380
}
Schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "A simple text description of the response"
    },
    "message": {
      "type": "string",
      "description": "A human-readable description of the response"
    },
    "path": {
      "type": "string",
      "description": "The URI of the original request"
    },
    "status": {
      "type": "number",
      "description": "The HTTP status code"
    },
    "timestamp": {
      "type": "number",
      "description": "The time of the response (expressed in seconds since January 1, 1970)"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Refresh action

Refresh
POST/api/refresh

If you specify a scope of OFFLINE when you login in, you can refresh your authentication bearer token by submitting it, along with your refresh token. This allows you to continue accessing secure systems without having to re-authenticate with your username and password.

  • token (string) - Your bearer token

  • refreshToken (string) - Your refresh token (received in the login response)

Example URI

POST https://auth.urjanet.net/api/refresh
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "token": "token-string",
  "refreshToken": "refresh-token-string"
}
Response  200
HideShow

If your refresh is successful you will receive the following response.

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "expires": "1443742827",
  "message": "Authentication Successful",
  "status": 200,
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJkZjUzMDViFX1BEUlwiXX0ifQ.qeJ63BD-VVDwL5xiK-wqFzdrTKH",
  "refreshToken": "B6970AAD-2E32-4BA3-A876-EEA60E57CC56",
  "type": "Bearer"
}
Schema
{
  "type": "object",
  "properties": {
    "expires": {
      "type": "number",
      "description": "The time this token will expire (expressed in seconds since January 1, 1970)."
    },
    "message": {
      "type": "string",
      "description": "A human-readable description of the response."
    },
    "status": {
      "type": "number",
      "description": "The HTTP status code"
    },
    "token": {
      "type": "string",
      "description": "The bearer token"
    },
    "refreshToken": {
      "type": "string",
      "description": "The refresh token"
    },
    "type": {
      "type": "string",
      "description": "The type of token returned in the response"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Response  401
HideShow

If your login is unsuccessful you will receive the following response. This can happen for a number of reasons, including:

  • The token or refreshToken you provided are incorrect

  • Your account has been locked

  • Your account has expired

Headers
Content-Type: application/json;charset=UTF-8
Body
{
  "error": "Unauthorized",
  "message": "Authentication Failed: Bad credentials",
  "path": "/api/refresh",
  "status": 401,
  "timestamp": 1443749329380
}
Schema
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "A simple text description of the response"
    },
    "message": {
      "type": "string",
      "description": "A human-readable description of the response"
    },
    "path": {
      "type": "string",
      "description": "The URI of the original request"
    },
    "status": {
      "type": "number",
      "description": "The HTTP status code"
    },
    "timestamp": {
      "type": "number",
      "description": "The time of the response (expressed in seconds since January 1, 1970)"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}

Example Usage

Once you have successfully logged in, you can authenticate with other Urjanet services by passing the Bearer Token in as an HTTP header.

These are just examples demonstrating how you would pass in the bearer token when calling another service.

Example action

Hello
GET/api/hello

Example URI

GET https://auth.urjanet.net/api/hello
Request
HideShow
Headers
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiJkZjUzMDViFX1BEUlwiXX0ifQ.qeJ63BD-VVDwL5xiK-wqFzdrTKH
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Hello world!"
}

Generated by aglio on 25 May 2016