Search
K

Connect your own portal

This guide is for Yuki customers who want to connect their own portal and companies to the Yuki API — an internal tool, a script or a report that works with your own data. If instead you build software that you offer to several Yuki customers, follow Build an integration for Yuki customers rather than this page.

Work through the steps in order. Steps 2 and 6 involve Yuki, so allow for some waiting time between them.

1. What you need first

  • A Yuki portal, with the companies you want to work with already in it. Your portal is the organization Yuki knows you by; see Portals and companies for how the two relate.
  • A user who administers integrations for your portal. One person should own this from end to end: they request access, create the application, generate its secret and keep it safe. That user needs to be able to sign in to your Yuki portal.

You do not need a separate developer organization or a published product. This route exists precisely so that a customer can connect their own portal without becoming a software vendor.

2. Requesting integration access from Yuki

Access to the developer portal for your own Yuki portal is arranged with Yuki rather than granted automatically.

Contact Yuki support to request integration access for your portal, and say which portal the request is for. Yuki will confirm when access is in place and tell you where to sign in.

Until that confirmation arrives, the remaining steps on this page will not be available to you, so do not create anything in advance.

3. Signing in to the developer portal and selecting your organization

Once Yuki confirms your access, sign in to the developer portal with the user that will administer the integration.

If that user can reach more than one organization, the developer portal asks which one you are working in. Choose the organization that corresponds to the Yuki portal you are connecting. Everything you create afterwards — the application, its secret, its integration — belongs to the organization you selected, so it is worth checking the selection before you continue.

4. Creating your application

Your application is the record that identifies your tool to Yuki. Create it in the developer portal and give it a name you will still recognise in a year's time.

Choose an interactive application type. Yuki API is an interactive API, meaning that there is user involvement while performing requests to the API. Choose a Web, Native or Single-Page application type. Observation: if you choose your application as a Service application, you may not be able to see Yuki's API for integration, and you will have to start again with a new application.

While configuring the application, fill in the URLs that Yuki uses to move a user between your tool and the sign-in screen:

  • Redirect URIs — where a user is returned to after they sign in successfully. This must match exactly what your tool sends, including the scheme, port and trailing slash.
  • Initiate Login URI and Logout URIs — where sign-in begins, and where a user is sent after signing out.

Even an internal tool needs these URLs, so decide early where your tool will run. A tool that only ever runs on one machine can use a local address, but it still has to be registered here.

5. Generating a secret

Your application authenticates itself with a Client Id and a secret. The Client Id is a public identifier and is safe to keep in configuration; the secret is confidential and behaves like a password for your application.

Generate the secret from the Credentials section of your application. You will be asked for a short description and an expiry.

The secret value is only visible at the moment of creation. Copy it into your secret store straight away — it cannot be retrieved afterwards, only replaced. Expiration time is up to 2 years for a secret, and an application can have up to 5 secrets. Keep a spare slot free so you can roll a secret over without an outage: create the new one, deploy it, then delete the old one.

Never place a secret in client-side code, in a repository, or in a support ticket.

6. Requesting the integration and choosing scopes

With the application created, request an integration with Yuki External API and choose the scopes it needs. Scopes are the permissions your tool is asking for — reading domains, writing domains, and so on.

Request only the scopes your tool actually uses. It is straightforward to ask for another scope later, and a narrow request is quicker to approve. The full list of available scopes, and what each one covers, is in the API reference — it is kept up to date there, so check it rather than guessing from an older document.

You will also be asked why you need the integration. A sentence describing what your tool does and which of your own companies it works with is enough.

Yuki then reviews the request. Tokens carrying Yuki API scopes cannot be issued until the integration is approved, so there is nothing more to configure while you wait.

7. After approval

Once the integration is approved, its status and its scopes are visible in the Integrations section of your application, and you can obtain your first token.

To confirm the setup works end to end:

  1. Send a user through the sign-in flow and check that they are returned to your redirect URI.
  2. Exchange the result for an access token, then call any read-only operation with it. A successful read means the application, the secret and the approved scopes are all in place. The exact requests are in the Authentication and Authorization Guide.
  3. Confirm you are reading the company you expected. See Portals and companies for which portal and companies a signed-in user can reach and how the selected company arrives in your application.

If a call is refused, compare the scopes on the approved integration with the scope the operation requires before changing anything else — a missing scope is the most common cause. API error codes covers what the API returns and what to do about it.

Still stuck? Contact Yuki support with your application name and what you tried.