Hirer Service Accounts

Hirer service accounts let your backend systems authenticate with the YunoJuno API and perform actions under your client account without any human in the loop. They are the recommended mechanism for any automated integration — workflow orchestration, finance and compliance tooling, internal portals, or AI agents that need to interact with YunoJuno.

Authentication uses the standard OAuth 2.0 Client Credentials grant (RFC 6749, §4.4). Your service account exchanges a long-lived client ID and client secret for a short-lived access token, which it then presents on API calls.

Note: This is a machine-to-machine flow. There is no end-user login, no consent screen, and no redirect. If you need a human user to authenticate and authorise actions, use the user-facing OAuth flow instead — see the separate guide on user authorisation.

What is a hirer service account?

A hirer service account is a non-human hirer on the YunoJuno platform. On YunoJuno, a hirer is a user who takes actions on behalf of your client account — typically a human such as a project sponsor or a procurement lead. A hirer service account is the same kind of entity, but represents an automated system rather than a person. Examples include a procurement portal, a compliance engine, or a concierge workflow.

Each service account has:

• A name you choose at provisioning time (e.g. Concierge, Procurement Portal, Compliance Sync). This name appears in audit logs and activity history against any action the service account performs.
• A client ID and client secret used to obtain access tokens.

You can provision multiple service accounts under the same client. We recommend doing so — giving each internal system its own service account limits blast radius if a single credential is compromised, makes it clear which system took which action.

How it works

A hirer service account is treated, for permission purposes, like a human hirer on the platform. Actions taken by a service account are attributed to the service account’s name in audit logs, so you can always trace which automated system performed a given action.

The flow at a glance

1. Your service account POSTs its client credentials to the token endpoint.
2. YunoJuno returns a short-lived bearer token — valid for one hour.
3. Your service account calls YunoJuno API endpoints, including the token in the Authorization header as a standard bearer credential.
4. When the token expires, repeat step 1 to get a new one.

Most OAuth client libraries handle the refresh transparently: they cache the token, detect expiry, and fetch a new one on demand. You should not need to implement this logic yourself.

Token endpoint

POST https://api.yunojuno.com/oauth/token

Request parameters (sent as application/x-www-form-urlencoded):

Successful response (200 OK, application/json):

1
{
2
  "access_token": "yj_at_01HXYZAB...",
3
  "token_type": "Bearer",
4
  "expires_in": 3600
5
}

• access_token — the bearer token to present on subsequent API calls.
• token_type — always Bearer.
• expires_in — token lifetime in seconds. After this time the token will no longer be valid.

Error response (400 or 401, per RFC 6749 §5.2):

1
{
2
  "error": "invalid_client",
3
  "error_description": "Client authentication failed."
4
}

Common error values:

• invalid_client — client ID or secret is wrong, the service account has been disabled, or the secret has been revoked.
• invalid_grant — something is wrong with the grant request, typically grant_type not being set to client_credentials.

Using the token

Include the access token on every API request:

Authorization: Bearer yj_at_01HXYZAB...

When the token expires, requests will return 401 Unauthorized with a WWW-Authenticate header indicating the token is expired. At that point your client should request a new token and retry.

Security considerations

• Treat your client secret like a password. Store it in a secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager, or similar). Never commit it to source control or embed it in frontend code.
• Secrets belong on your backend only. The client credentials grant is specifically designed for confidential clients — servers that can protect a secret. Do not use this flow from browsers, mobile apps, or desktop clients.
• Rotate secrets periodically. You can provision a second secret for the same service account, migrate traffic to it, and retire the old one with no downtime.
• Revoke compromised secrets immediately. Once a secret has been revoked, all access tokens that were provisioned against it will also be revoked. If there is a breach event, it is important you revoke the client secrets as soon as possible and provision a new client secret.

Popular OAuth client libraries

You do not need to implement the client credentials flow by hand. Well-maintained OAuth libraries exist for all major languages and will handle token acquisition, caching, refresh on expiry, and retry with the new token. We recommend the following:

Any library that implements RFC 6749 §4.4 (Client Credentials grant) will work with our token endpoint. If your preferred language isn’t listed above, look for a general-purpose OAuth 2.0 client library in your ecosystem’s package registry.