Web API

Web API is used when you build RESTful applications running in a browser, or for integration when a server is communicating with other servers.

Simple web API example:

using Microsoft.AspNetCore.Mvc;

[Route("api/samples")]
[ApiController]
public class SampleApiController : Controller
{
    [Route("")]
    [HttpGet]
    public IActionResult GetSampleData()
    {
        return Ok(new
        {
            Data = new[]
            {
                "item1",
                "item2",
                "item3"
            }
        });
    }
}

Service Account

A service account is used to secure integrations where another system is connected directly to Litium.

When you create integrations to Litium you can let the consumer identify as a real user (person) in Litium or by using the service account. The benefit of using the service account over a real user account is that the service account is not allowed to login on the public site or back office, but can still have the same permissions as an administrator.

Service accounts are managed in back office, Settings > System settings > Service accounts. Each service account has a username and password that is used for identification.

Authorization

OAuth2 authorization flow for client credentials is used to create the JWT. With this flow the username and password is sent to the server and a JSON answer is returned with the JWT as an access token, along with information about when the token expires. The token can be reused for multiple requests until the token expires.

The token endpoint used in a POST request to create the JWT is https://domain/connect/token, and the required payload is “grant_type=client_credentials&client_id=[service account id]&client_secret=[service account password]”.

Example

Request

POST /connect/token HTTP/1.1
Host: domain
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=user&client_secret=password

Response

{
    "access_token": "J4HlhawWVlIse-7-CwlqlFLVBtS1YBw01sXLzFuLehJt6JVWkJjQ236EbyRw7L5cSDC5opv9AmS7eu7fZRFUQ2Jy9
dyGbZiI3MahSYQTjoZ3NsaRwNL6NYF2SRqZlxKk7Hf8pjgca2eui2mEbo4u2qFowzWrP6I8PNckyFB91t-6oM6fNqwB08DOCzvPxYQNKMFB6hz
1BHvv7xswFvrVRl_8fFTy5pRPN5cbCEButL-lJIJqm0fl193g2g9I_HvBDc6FFlcfx6t_ecG-V3xpmfInFjROm1o8yA6h8nCfsxbnQm2Q0aVYw
Lye22tCienKME3dL9yJy1cmRYXkJ7BH-rvaqlnG4BSc948GtjIxI3k6P1kWLG1hYskFGS0oancj",
    "token_type": "bearer",
    "expires_in": 599
}

In subsequent calls to the server the access token is sent as an authorization header in the request, the authorization type should be Bearer.

Token usage example request

GET /api/example/productlist HTTP/1.1
Host: domain
Content-Type: application/json
Authorization: Bearer J4HlhawWVlIse-7-CwlqlFLVBtS1YBw01sXLzFuLehJt6JVWkJjQ236EbyRw7L5cSDC5opv9AmS7eu7fZRFUQ2Jy9
dyGbZiI3MahSYQTjoZ3NsaRwNL6NYF2SRqZlxKk7Hf8pjgca2eui2mEbo4u2qFowzWrP6I8PNckyFB91t-6oM6fNqwB08DOCzvPxYQNKMFB6hz
1BHvv7xswFvrVRl_8fFTy5pRPN5cbCEButL-lJIJqm0fl193g2g9I_HvBDc6FFlcfx6t_ecG-V3xpmfInFjROm1o8yA6h8nCfsxbnQm2Q0aVYw
Lye22tCienKME3dL9yJy1cmRYXkJ7BH-rvaqlnG4BSc948GtjIxI3k6P1kWLG1hYskFGS0oancj

Support OpenId 

Litium also supports OpenId with automatic configuration of the clients. The endpoint is https://domain/.well-known/openid-configuration .

Sample scopes and claims supported :  

 "scopes_supported": [
    "openid",
    "profile",
    "litium",
    "offline_access"
  ],
  "claims_supported": [
    "sub",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
    "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
    "http://schemas.litium.com/identity/claims/extrainfo",
    "http://schemas.litium.com/identity/claims/impersonatedforname",
    "name",
    "family_name",
    "given_name",
    "middle_name",
    "nickname",
    "preferred_username",
    "profile",
    "picture",
    "website",
    "gender",
    "birthdate",
    "zoneinfo",
    "locale",
    "updated_at",
    "litium"
  ],