Skip to main content

API Usage

For simplifying and accelerating the development, configuration and integration of Nevis ID, REST and SOAP APIs are available.

To access Nevis ID with an API client, the domain name should be constructed as https://api-{environment}.{instance}.getnevis.net, for instance: https://api-test.abc123.getnevis.net. For convenience, “live” environment is not specified in the domain name, but other environments are.

On this domain all existing API endpoints of the deployed Nevis components are exposed (in the Example project they are: nevisIDM, nevisAdmin4 and nevisMeta). Nevis components API documentations are available on our dedicated API docs site.

The API has to be called with a bearer token which has to be created first.

API Creation​

  1. Create a Device Credential Policy in the API Key client. If missing, with the following contents:

    minLength=32
    checkDictionary=false
    maxLength=100
    minNonAlnum=0
    minNonLetter=0

  2. In the client API Key create a new user, you can use whatever login ID you want, but it is recommended to adhere to consistent naming standards (eg.: api-insert_name).

    • Ensure the created user is a technical user.
    • Fill out name and e-mail address if required.

  3. Open the default profile and add the IDM Role SoapTechUser and restrict it to the Default client. This limitation is meant as a sefaguard and is recommended for all standard technical users.

  4. Go back to the user.

  5. Create a random 64 chart secret:

python3 -c "import secrets; print(secrets.token_urlsafe(48))"
# => 6LFQjP86HDFsv-jQgEyFnUNjECriMZoblEsrkFofCbiLmqDojJ8xjFm5hj78yLPk

  1. Create a new credential:

    1. Type: Device Password
    2. Policy: Policy created above
    3. New value and confirmation: The value generated in step 5 (6LFQjP8…)
    4. Save the created credential

  2. Get the user ext ID, and credential ext ID.

  3. Create the bearer token by combining {userExtId}:{credExtId}:{randomSecret}

echo -n '1054:1024:6LFQjP86HDFsv-jQgEyFnUNjECriMZoblEsrkFofCbiLmqDojJ8xjFm5hj78yLPk' | \
  base64 | tr -d '='
# => MTA1MjoxMDQ1OjVUMkRRSXY4a0Y0QWxjeVN5VVBkVThRRzFpTlB4YUJOUXpOeEFvWkFoVWNkWHFVVGVHeXE0amRiV255T1dvTnE
  1. API Token created.

Nevis SecToken​

With the nevisIDM and nevisMeta REST services (“idm-rest” and “meta-rest” patterns) there is a “Nevis SecToken” pattern assigned. The userId in the SecToken will be the userId of the nevisIDM user that the Bearer token is associated with.

Example REST API queries​

nevisIDM​

$ curl -X GET "https://api.abc123.getnevis.net/nevisidm/api/oic1.0/userinfo"
  -H "Authorization: Bearer {your token}"
{"sub":"1389"}

nevisMeta​

$ curl -X GET "https://api.abc123.getnevis.net/nevismeta/rest/v2/modules/oauthv2/setups" \
  -H "Authorization: Bearer {your token}"
{
  "setupIds" : [ "00000000000000000000000000000000" ]
}

nevisAdmin4​

$ curl -X GET "https://api.abc123.getnevis.net/nevisadmin/api/v1/me" \
 -H "Authorization: Bearer {your token}"
{
  "userKey" : "admin",
  "email" : "[email protected]",
  "type" : "local"
}