Search
K

Authentication and Authorization Guide

Yuki’s API uses Visma Connect for secure authentication and authorization of API requests. This guide provides step-by-step instructions on how to authenticate and authorize requests using Visma Connect tokens.

By following the above steps and guidelines, you can seamlessly authenticate and authorize requests to interact securely and effectively with Yuki’s API using Visma Connect. For further details, consult the Visma Connect Documentation

Overview

What is Visma Connect

Visma Connect is a robust identity and access management platform that provides OAuth 2.0 and OpenID Connect services for secure API authorization. Using Visma Connect, you can ensure that your API is accessed safely, with proper user authentication and token management.

Obtaining Access Tokens

To interact with Yuki’s API, you must first obtain an access token from Visma Connect. This token serves as proof of authorization when making API requests.

1. Register your application

  • Before you can obtain a token, you need to register your application with Visma Connect with a previously assigned SSO Administration login.
  • Head to the Visma Developer Portal and log in with your developer account.
  • Register your application to receive a client ID and client secret.

2. Authorization Code Flow

2.1. Direct Users to Visma Connect Authorization
  • Redirect users to the Visma authorization endpoint. The user will be prompted to log in and authorize access.

[GET] https://auth.visma.com/authorize with the following parameters:

{
  "response_type": "code",
  "client_id": <your_application_client_id>,
  "redirect_uri": <URI_to_redirect_users_after_authorization>,
  "scope": <scopes_you_are_requesting>,
}
  • Receive Authorization Code: After authorization, Visma redirects back to your specified redirect_uri with an authorization code
  • Exchange Authorization Code for Access Token: Use the obtained authorization code to request an access token to [POST] https://auth.visma.com/token with the following parameters:
{
  "grant_type": "authorization_code",
  "code": <authorization_code_recieved>,
  "redirect_uri": <URI_to_redirect_users_after_authorization>,
  "client_id": <your_client_id>,
  "client_secret": <your_client_secret>
}
2.2. Making Authorized API Requests

Once you have obtained an access token, include it in your HTTP requests to Yuki API

curl -X GET https://api.yukisoftware.com/v1/resource \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
2.3. Handling Token Expiration and Refresh

Tokens expire after a set period. Use the refresh token to obtain a new access token without user intervention.

[POST] https://auth.visma.com/token

{
  "grant_type": "refresh_token",
  "refresh_token": <the_issued_token>
}

3. Scope Management

Define scopes during the authorization process to control the level of access users have to your API

Example Scopes

  • yukiapi:domain:domains:read Allow users to read information regarding domains
  • yukiapi:domain:domains:read Allow users to write information regarding domains

4. Security Best Practices

  • Keep Client Secret Safe: Ensure that your client secret is not exposed in client-side code or shared with unauthorized parties.
  • Use HTTPS: Always make authorization and API requests over HTTPS to ensure secure data transmission.