finautapi - API access for FinAut clients¶

Developer instructions for using the FinAut API¶

This document describes the steps involved in getting access to and using the FinAutApi.

Getting a user and a client¶

The first thing you need to do, is to contact a developer at Norsk Test AS to get a username and a password. To do this, you must call Norsk Test at +47 78 97 35 00.
The user that is created will be linked to one or more FinAut members (companies). Which company this user should have access to must be specified when calling Norsk Test.
Norsk Test will communicate the username and password securely to you.
An OAuth Toolkit / Application will be created for you. This will provide a client-id and a client-secret that you will have to use to retrieve a token.

Once you have your login credentials you need to visit https://api.norsktest.no/finautapi/v1/api-auth/login/?next=/o/applications/ to retrieve your application data.

Using the FinAutApi¶

The FinAutApi uses the OAuth2 Client Credentials Flow.

To make an api-call to one of the endpoints, you must first get a token.

This is done by posting a request like this cUrl example (newlines inserted for clarity):

$> curl -X POST -d "grant_type=client_credentials&
                    client_id=[client_id]&
                    client_secret=[client_secret]" https://api.norsktest.no/o/token/

The response will look like this:

{
    "access_token": [token],
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "read write"
}

Note that the token is valid for 3600 seconds (1 hour). When the token has expired, you will get a 401 error with detail saying "Authentication credentials were not provided." Use the token when calling the endpoints (cUrl example):

$> curl -H "Authorization: Bearer [token]" https://api.norsktest.no/finautapi/v1/user/

Throttling¶

The FinAutApi is setup with a throttling mechanism that will pause access to the API if more than 200 requests are sent within one hour.

Pagination¶

All of the list-endpoints have a page size of 100. This means that each call will return max 100 records at the top-level. Page numbers are 1-based, i.e. the first page is page number 1.

Webhook¶

The FinAutAPI can send exam-results and/or user-statuses back to predefined urls at your location (typically your LMS-system). Norsk Test must get the urls to post to for your organization. When that has been setup, the FinAutAPI will post new/changed results/userstatues to that url. The format of the data posted, can be found in the endpoint documentation.

UserLogin¶

This is a functionallity that enables external systems to get an encrypted user id from the FinAut portal that can be stored alongside the id of the user in the external system to uniquely identify the user. This requires the user to log in the first time this endpoint is triggered. The API will then post the encrypted user id to a pre-defined url on the client side. The encrypted user id can then be used later to push information regarding completed courses to FinAutAPI.

To enable this functionality, Norsk Test AS must first create a client record in the api together with the url to post the encrypted user id to and the url that the user should be redirected to after logging in.

The <ext-user-id> is a unique identifier of a user on the client side.

Sequence diagram:

FinAutApi endpoint documentation¶

Once you have a username and a password, you can access the FinAutApi endpoint documentation at API-documentation

What does the FinAutApi do?¶

The FinAutApi is created to make life easier for the candidate administrators (referred to as BA “Bedriftsansvarlig”).

Specifically, this means transferring user data between your internal systems and FinAut’s system.

E.g. your HR or LMS systems can use the FinAutApi to “automatically” create a candidate in your company and assign them to one of the authorization schemes.

Here are some of the features that the FinAutApi can provide for the companies:

Create a new BA.
Create a new candidate.
Create a new TL.
Give a user a new (additional) role.
Update demographical data on a user.
Sign a candidate up to one or more of FinAut’s authorization schemes.
Withdraw or set a user on hold in one or more of the authorization schemes.
Change a candidate’s department.
List all candidates that your account has access to.
Retrieve information on one specific candidate, based on the SSN or user-id or employee_alias.
List all companies and departments that your account has access to.
Get the current status of a candidate in one of the authorization schemes.
Get all results for a specified user based on the users SSN or employee_alias.
Get all results that has been created after a given from-date.
Send exam-results back to a webhook at your location.

Glossary¶

Company¶

A company is a company that is member of FinAut. Typically a bank/financial institution or an insurance company. All candidates must belong to exactly one company.

Department¶

A department is a sub-unit within a company. All candidates must be assigned to exactly one department (in addition to one Company).

BA¶

A BA is a person who administers candidates in one or more companies. It is possible to have more than one BA per company.

TL¶

A TL is a testleader whose role it is to control and give access to candidates taking a FinAut exam.

Candidate¶

A person in a company who is entered as a candidate in one or more of the Authorization Schemes that FinAut manages.

Authorization schemes¶

FinAut manages multiple authorization schemes where candidates can become authorized advisors. A list of these schemes can be found in the “ordninger” endpoint. Check out the API documentation for details.

SSN¶

The SSN is required on all users in the FinAut system. In Norway this is called “Fødselsnummer” and must be 11 digits. Note: Users with a foreign SSN cannot be created using the API. These must be created manually in the FinAut portal.

User-ID¶

All candidates in FinAut’s system has an internal identification number in addition to the SSN.

Status¶

All candidates has a current status in all of the authorization schemes that the candidates is or has been signed up to. The status tells if the candidate is authorized (or not), or if they are set on hold or withdrawn.

In addition to the current status, the API also contains the status history of the candidates in each of the authorization schemes that they have been signed up to.

employee_alias¶

Internal employment id. This field can be used to identify a user in FinAut by an internal id within a company. There is no field-validations or duplicate-checks for this field.