API for sluttbruker og 3. parter (test)

Endret Tue, 28 Jan ved 2:24 PM

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

Currently, we are testing our API directly with several businesses and integration partners. We need to generate their client_secret manually, but we will soon have automated processes to simplify API connection. Systima has an open and flexible API strategy.

Currently we test to our dev server. We do new updates on this server multiply times a day, and we also do a lot of API changes. We currently want to test this server so it is efficient for us to possibly update the API if there is a desire for changes. We will later test against a more stable server.

INNHOLDSFORTEGNELSE

Swagger (external API)
Step 1 - Get dev access
Step 2 - Send us needed info
Step 3 - Set up oAuth
Step 4 - Connect to live API
Step 3 (alternative) - Set up using login API

Swagger (external API)

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

Username: external

password: 123456789

Step 1 - Get dev access

Send us a message so we can give you access to our dev server, and create your client_secret

You can send a message here and please send this:

- Info about you

- Organization number

- Phone number

- Email

Step 2 - Send us needed info

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

Step 3 - Set up oAuth

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.

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:

A registered application in the Systima Developer Portal (Set up in step 2)
Client credentials (client ID and client secret received after registration with Systima)
Understanding of OAuth 2.0 principles
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.

Token Exchange 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": "string"
}

Note: code parameter is a code that would be received during the redirect in the authorizationCode query parameter.
grantType is a part of OAuth2 specification and is hardcoded for our current implementation with authorization_code value

Response

{
  "accessToken": "string",
  "expiresAt": "2024-01-21T12:00:00Z"
}

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

Step 4 - Connect to live API

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

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

If you for some reason can not use oAuth, you can check alternative step 3.

If you want to use login API with access token, you can follow this step instead:

Use this endpoint to get an access token

https://api-dev-systima.azurewebsites.net/swagger-external/#/Auth/AuthController.login

This API is protected by client_secret that we sent you

Please use email and password of your user, that you registered in https://app.dev.systima.no

Request:

curl -X 'POST' \
  'https://api-dev-systima.azurewebsites.net/api-external/auth' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "USER_EMAIL",
  "password": "USER PASSWORD"
}'

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJjYmNkNjkzMi1lODkxLTQzNTktOWZlOS04YjU1NDg3MDJiNTAiLCJpYXQiOjE3MDMwODg4MzgsImV4cCI6MTcwMzE3NTIzOH0.kyAQ12duXMIuSV-chmZETeOghSJzeOYxRvFtRxdkAq1",
  "expiresIn": 86400,
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJjYmNkNjkzMi1lODkxLTQzNTktOWZlOS04YjU1NDg3MDJiNTAiLCJpYXQiOjE3MDMwODg4MzgsImV4cCI6MTcwMzY5MzYzOH0.kXhZqBe8OSDC0hwaK3LO51qTz5spfMFi9zgXmwLnout"
}

In case when access token has expired use the API to renew the access token

https://api-dev-systima.azurewebsites.net/swagger-external/#/Auth/AuthController.refreshToken

Request

curl -X 'POST' \
  'https://api-dev-systima.azurewebsites.net/api-external/refreshtoken' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ6.eyJ1c2VySWQiOiJjYmNkNjkzMi1lODkxLTQzNTktOWZlOS04YjU1NDg3MDJiNTAiLCJpYXQiOjE3MDQ2OTk1MTksImV4cCI6MTcwNzI5MTUxOX0.-w1rQWNSGCNzE_U3DQkw6uabVBYFZv2OAjn5JKhgBRs"
}'