Lightelligence API (1.0.0)

Download OpenAPI specification:Download

API Specification of OSRAM Lightelligence

Authentication

oAuthSample

Security scheme type: OAuth2
authorizationCode OAuth Flow
Authorization URL: https://id.lightelligence.io/v1/id/auth/realms/olt/protocol/openid-connect/auth
Token URL: https://id.lightelligence.io/v1/id/auth/realms/olt/protocol/openid-connect/token
Scopes:

    bearerAuth

    Security scheme type: HTTP
    HTTP Authorization Scheme bearer

    oauth

    Get basic realm info

    Get basic realm info. This includes the public key, which can be used to ensure a JWT was correctly signed by this idp (identity provider). The provided public_key is not PEM encoded, so for JWT verification it still needs PEM padding. To verify any issued JWT the key can be padded like:

    -----BEGIN PUBLIC KEY-----
    {{ACTUAL KEY}}
    -----END PUBLIC KEY-----

    olt-permissions: []
    Authorizations:

    Responses

    200

    Success

    500

    Internal Server Error response

    get /id/auth/realms/olt

    OAuth2 Production Environment

    https://id.lightelligence.io/v1/id/auth/realms/olt

    Response samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAjD3labyD/J7o6CWrWSbrDg90nY9YD40dAG1IJVixKxHIZc1u/yOUWHFSeGUlf39cuMKZuj82wJpHKuFLDnh/B9ckvq93VebEHtOwv/P1KavaSimoyZQ49k+K3sRX+6zTY0/udK9S+hKQfJOjmFRXM515efUYJyJ5gBgCvw16RAEgDE2IhfXUf6trcOwiJj2OBvIglutup4iSO99SFmMoY+23MQ0zU9fGTx7vbcygBJAhbnHQlFElPCo6pqWpuAl5Wi7xaddIFG7apRESNKFZBJHzLV2JQac/arCMJOX3HRTK19dZpasLbUJ9lwj7XLT8Kk7h9FdBX4ImD+aTryF6CQIDAQAB"
    }

    Get authorization code

    This is the URL endpoint for the Authorization Code Flow to get a temporary code to later exchange for a token. Use this code with the /token endpoint to get a user token.

    Userinfo: provide optional scopes email profile to include more user information in authentication session.
    Next step is to exchange the authorization code for a token at GET /protocol/openid-connect/token

    olt-permissions: []
    Authorizations:
    Request Body schema: application/x-www-form-urlencoded
    client_id
    required
    string

    The ID of the OAuth2 client

    redirect_uri
    required
    string <uri>

    Valid redirect uri for the current client

    scope
    required
    string

    Space delimited list of scopes. When requesting an access token the scope openid must be used to ensure the responding access_token is fully valid.
    Optional scopes:
    email - includes email in auth session.
    profile - includes profile info (eg firstname, lastname) in auth session.

    response_type
    required
    string
    Value: "code"

    Response type for auth grant flow

    response_mode
    required
    string
    Enum: "form_post" "query" "fragment"

    Define how the response should be returned

    nonce
    string

    Required if using "response_mode=form_post"

    Responses

    200

    Success, callback to redirect_uri

    400

    Bad Request response.

    500

    Internal Server Error response

    post /id/auth/realms/olt/protocol/openid-connect/auth

    OAuth2 Production Environment

    https://id.lightelligence.io/v1/id/auth/realms/olt/protocol/openid-connect/auth

    Get access token

    Openid endpoint to get an access token. Based on the grant_type different flows work here.

    When using refresh_token as grant_type the new returned access token will be scoped with the same tenant as the previous one. Optionally the header tenant can be used to obtain a new access token for the user with a different tenant. This may not always work (the user might not be part of the tenant, the application might not be installed to the tenant or other reasons can forbid this operation).

    Tip: Get user information by exchanging the token for userinfo at GET /protocol/openid-connect/userinfo

    olt-permissions: []
    Authorizations:
    header Parameters
    tenant
    string <uuid>

    Set the tenant the token should be valid for. This header is only supported when the grant_type is set to refresh_token.

    Request Body schema: application/x-www-form-urlencoded
    client_id
    required
    string

    The ID of the OAuth2 client

    client_secret
    string

    Secret to use with your clientId. (Not required if using 'public' client)

    grant_type
    required
    string
    Enum: "authorization_code" "client_credentials" "id_token" "refresh_token"

    OAuth2 grant types supported by OLT

    redirect_uri
    string <uri>

    Valid redirect uri for the current client
    - Required if using authorization_code grant flow

    code
    string

    The Authorization Code if using Authorization Code Flow

    scope
    string

    Space delimited list of scopes. When requesting an access token the scope openid must be used to ensure the responding access_token is fully valid.
    Optional scopes:
    email - includes email in auth session.
    profile - includes profile info (eg firstname, lastname) in auth session.

    Responses

    200

    Success

    400

    Bad Request response.

    500

    Internal Server Error response

    post /id/auth/realms/olt/protocol/openid-connect/token

    OAuth2 Production Environment

    https://id.lightelligence.io/v1/id/auth/realms/olt/protocol/openid-connect/token

    Response samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
    • "expires_at": "2019-10-20T23:19:30Z",
    • "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U",
    • "scope": "openid profile email"
    }

    Get UserInfo for current user

    The UserInfo endpoint is an OAuth 2.0 protected resource where client applications can retrieve consented claims, or assertions, about the logged in end-user. This is retrieved by using a valid access_token for the OLT platform through the Authorization header.

    olt-permissions: []
    Authorizations:

    Responses

    200

    Success

    400

    Bad Request response.

    401

    Unauthorized response.

    500

    Internal Server Error response

    get /id/auth/realms/olt/protocol/openid-connect/userinfo

    OAuth2 Production Environment

    https://id.lightelligence.io/v1/id/auth/realms/olt/protocol/openid-connect/userinfo

    Response samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "sub": "123e4567-e89b-12d3-a456-426655440000",
    • "emailVerified": true,
    • "name": "Richard Feynman",
    • "preferred_username": "foo@bar.com",
    • "given_name": "Richard",
    • "family_name": "Feynman",
    • "tenant": "123e4567-e89b-12d3-a456-426655440000",
    • "email": "foo@bar.com",
    • "twoFactorAuthEnabled": true
    }

    notifications

    Notifications are created and configured by users. They use filters to process events and then trigger a notification that is sent to a specific channel (i.e. email) depending on its configuration.

    Retrieve tenant notifications

    Retrieves a list of notifications containing filter information as well as notification template.

    By default the list is sorted by creation datetime in descending order. So, most recently created entry goes first.

    olt-permissions: ["notification:read"]
    Authorizations:
    query Parameters
    page
    integer >= 0
    Default: 0

    The number of the result page starting with 0.

    pageSize
    integer [ 1 .. 100 ]
    Default: 20

    The number of result per page.

    Responses

    200

    Success - A notifications list.

    400

    Bad request

    401

    Authentication required

    403

    Action is forbidden

    500

    Internal Server Error

    get /notifications

    Production Environment

    https://api.lightelligence.io/v1/notifications

    Response samples

    Content type
    application/json
    Copy
    Expand all Collapse all
    {
    • "meta":
      {
      },
    • "data":
      [
      ]
    }

    Create notification

    Request a new notification to be created.

    olt-permissions: ["notification:write"]
    Authorizations:
    Request Body schema: application/json
    notificationTemplate
    required
    object

    Notification template

    notificationFilter
    required
    object

    Filter which allows to receive notifications for specific events; The filter conditions ("deviceEvent", "deviceId", "deviceTag", etc) are treated as an AND, the values provided in the arrays are treated as an OR.

    Responses

    200

    Success - A notification has been created.

    400

    Bad request

    401

    Authentication required

    403

    Action is forbidden

    500

    Internal Server Error

    post /notifications

    Production Environment

    https://api.lightelligence.io/v1/notifications

    Request samples

    Content type
    application/json
    Copy
    Expand all Collapse all