API for 3rd part and end users (Systima)

This article is for testing and implementing our external API. This applies to both company level and third-party integration partners.

We have two ways to integrate with Systima, depending on if the user should start the integration from Systima UI or Integration parter UI:

• OAuth - User starts the process from Integration partner UI
• RedirectURL - User starts the process in Systima UI (Integration screen)

Both solutions will be displayed in our integration screen, but OAuth can not be started from there.

INNHOLDSFORTEGNELSE

• Swagger (external API)
• Step 1 - Get staging access
• Step 2 - Send us needed info
• Step 3.1 - Set up redirectURL (Alternative 1 - Start from Systima UI)
  • Step 3.1.1 Get authorization code and info from redirectURL
  • Step 3.1.2: Token Exchange (/token endpoint)
  • Step 3.1.3: Exchanging refresh token to new access token
• Step 3.2 - Set up oAuth (Alternative 2 - Start from integrator UI)
  • Step 3.2.1: User Login (/authorize endpoint):
  • Step 3.2.2: Token Exchange (/token endpoint)
  • Step 3.2.3: Exchanging refresh token to new access token
• Step 4 - Connect to live API

Swagger (external API)

All available endpoints can be found in our swagger. We have many more endpoints that are not exposed on the external api. If you need endpoints that are not shown here, just contact customer service at post@systima.no

Swagger link: https://api-stage-systima.azurewebsites.net/swagger-external/

Username: external

password: 123456789

Step 1 - Get staging access

Send us a message so we can give you access to our staging server.

You can send a message here and please send this:

- Short introduction of your company

- Organization number

- Phone number

- Email

Step 2 - Send us needed info

Fill out this form, so we have more information about the integraiton.

Depending on integration type, we will arrange the needed set up. We will send you clientId and clientSecret.

Step 3.1 - Set up redirectURL (Alternative 1 - Start from Systima UI)

RedirectURL should be used if you want the user to start the integration process from Systima UI. This is recommended in most cases.

Introduction

RedirectURL allows the integration partner to be placed in Systimas "Integrations" page. From this page, the users can easly activate the intregration by the click of a button. User can also read information about the integration, price to have the integration (if any) and link to terms, more information etc.

What is the redirect URL?

When setting up the integration, Systima ask you for a redirectURL. This url is mainly used for two things:

1. Sending information from Systima to your integration
2. Sending the user to your integration landing page

Every time a user connects to your integration from the Systima integration page, Systima will generate a authorizationCode that can be exchanged for a access token. This access token that can be used for requests to the company that activated the integration. This authorizationCode is included together with other needed information when sending the user to your landing page.

Your integration must process the information needed and complete the integration setup on your end. 

Step 3.1.1 Get authorization code and info from redirectURL

You provide us a redirect URL, example:

https://Integration.MySystimaIntegration.no

When a user activates the integration in Systima integration page, we will call your reidrect URL and add this data:

companyId: 7fa-7ilj0-a7a9-o47i9-93k982d63
companyName: Integration AS
organizationNumber: 123456789
authCode: oynhbGhiOkJIj8I1Ninsjnj59C

{
  "code": "string",
  "clientId": "string",
  "clientSecret": "string",
  "redirectUri": "string",
  "grantType": "authorization_code"
}

Response

{
  "accessToken": "string",
  "expiresAt": "5976-02-15T12:15:06!9906273272743590235806495",
  "refreshToken": "string",
  "refreshTokenExpiresAt": "8170-18-20T25:00:2771504985799316448"
}

The received accessToken then can be used to access Systima API endpoints.

The received refreshToken can be used to refresh the accessToken.

Step 3.1.3: Exchanging refresh token to new access token

Request Body

{
  "clientId": "string",
  "clientSecret": "string",
  "redirectUri": "string",
  "grantType": "refresh_token",
  "refreshToken": "string"
}

Example of how the integration would look in Systima UI

Step 3.2 - Set up oAuth (Alternative 2 - Start from integrator UI)

OAuth should be used if you want the user to start the integration process from the integrators UI.

This documentation provides a comprehensive guide to implementing OAuth authentication for Systima's External API. OAuth enables secure delegated access to Systima's resources, allowing third-party applications to interact with the API on behalf of users without exposing their credentials.

Introduction

The OAuth integration is started in the integration parters UI, where the user can click somwhere to start the integration process. When user starts the process, they get redirected to Systima UI to log in with username and password. When user has logged in, the integration partner will receive needed information to set up the complete integration for the users company.

Key Features

• Secure token-based authentication
• Industry-standard OAuth 2.0 implementation

Before You Begin

To integrate with Systima's OAuth authentication system, you'll need:

1. A registered application in the Systima Developer Portal (Set up in step 2)
2. Client credentials (client ID and client secret received after registration with Systima)
3. Understanding of OAuth 2.0 principles
4. HTTPS-capable development environment

This guide will walk you through the authentication process, from initial setup to implementing the various OAuth flows in your application.

Starting OAuth process
1. Redirect the user to  https://app.systima.no/oauth/login?clientId={{your-client-id}} 
2. After successful login, we will redirect back to the `redirectUri` appending `authorizationCode` and `oauthClientId` as query params.  

Step 3.2.1: User Login (/authorize endpoint):

POST /token

Content-Type: application/json

The client application sends the user's email, password, and client ID to the /authorize endpoint.

If the credentials are valid, the server responds with an authorizationCode, redirectUri, and state.

Request Body 

{
  "email": "user@example.com",
  "password": "user-password",
  "clientId": "your-client-id",
  "state": "optional-custom-state"
}

Response

{
  "redirectUri": "https://yourapp.com/callback",
  "authorizationCode": "abc123xyz",
  "oauthClientId": "your-client-id",
  "state": "optional-custom-state"
}

Step 3.2.2: Token Exchange (/token endpoint)

POST /token
Content-Type: application/json

This endpoint exchanges an authorization code for an access token.

Request Body

{
  "code": "string",
  "clientId": "string",
  "clientSecret": "string",
  "redirectUri": "string",
  "grantType": "authorization_code"
}

Note: code parameter is a code that would be received during the redirect in the authorizationCode query parameter. 

grant_typeis part of the OAuth2 specification (RFC 6749). Our implementation supports both the authorization_code and refresh_token flows, making the grant_type configurable based on the use case.

Response

{
  "accessToken": "string",
  "expiresAt": "2168-17-28T14:57:39<61958552513315955142722756880042736416206",
  "refreshToken": "string",
  "refreshTokenExpiresAt": "8612-02-22T03:32:11=510618866432243566821670Z"
}

The received accessToken then can be used to access Systima API endpoints.

The received refreshToken can be used to refresh the accessToken.

Step 3.2.3: Exchanging refresh token to new access token

Request Body

{
  "clientId": "string",
  "clientSecret": "string",
  "redirectUri": "string",
  "grantType": "refresh_token",
  "refreshToken": "string"
}

Example of how the integration would look in Systima UI

Step 4 - Connect to live API

Use this link when you want to connect to live API:

https://api-systima.azurewebsites.net/api-external