# Auth.md

Skillhive is a Nordic skills & learning platform operated by Intunex Oy
(Helsinki, Finland). This document tells humans and AI agents exactly how
authentication works, and — just as importantly — what does **not** exist, so
no client guesses a flow that is not implemented.

There are two separate systems. Do not confuse them.

| System | Purpose | Agent-relevant |
| --- | --- | --- |
| Skillhive product API (`https://intunex.skillhive.com/api/v3`) | The real product: skills, people, learning data | Yes |
| This marketing site (`https://www.skillhive.com`) | Public content + a private CMS login for Intunex staff | No |

## 1. Skillhive product API (the one agents want)

- Base URL: `https://intunex.skillhive.com/api/v3`
- Specification: OpenAPI 3.1 at
  <https://intunex.skillhive.com/api/v3/docs.jsonopenapi>
- Human documentation: <https://intunex.skillhive.com/api/v3/docs.html>
- Roughly 70 paths, including `skills`, `user-skills`, `work-experiences`,
  `educations`, `recommendations`, `groups`.

Each customer runs on their own tenant host; `intunex.skillhive.com` is
Intunex's own instance and is the reference deployment for the specification.

### Authentication flow

Username/password exchange for a JWT bearer token. **This is not OAuth 2.0 and
not OpenID Connect.**

```http
POST https://intunex.skillhive.com/api/v3/auth
Content-Type: application/json

{ "username": "<user>", "password": "<password>" }
```

The response contains a JWT. Send it on every subsequent request:

```http
Authorization: Bearer <jwt>
```

### How to obtain credentials

**API access is included in a Skillhive customer subscription.** Credentials are
requested from <info@intunex.fi>.

- There is **no public trial access**.
- There is **no self-service registration**, no signup endpoint and no dynamic
  client registration.
- An agent must therefore direct the asker to email <info@intunex.fi> (or, if
  they are not yet a customer, to <https://www.skillhive.com/skillhive-demo>)
  rather than attempt any registration flow.

Include in the request: organisation name, existing Skillhive tenant (if any),
intended use case and data scope, and a responsible technical contact.

```json
{
  "agent_auth": {
    "resource": "https://intunex.skillhive.com/api/v3",
    "auth_type": "bearer_jwt",
    "token_endpoint": "https://intunex.skillhive.com/api/v3/auth",
    "token_endpoint_method": "POST",
    "credential_types": ["password_grant_jwt"],
    "identity_types": ["human-delegated"],
    "register_uri": "mailto:info@intunex.fi?subject=Skillhive%20API%20access",
    "self_service_registration": false,
    "public_trial": false,
    "access_requires": "active Skillhive subscription",
    "revocation_uri": "mailto:info@intunex.fi?subject=Skillhive%20API%20revocation",
    "openapi": "https://intunex.skillhive.com/api/v3/docs.jsonopenapi"
  }
}
```

### Example use case

Building a CV or competence profile for a person: authenticate as above, then
read `user-skills`, `work-experiences` and `educations` for that user and
compose the document. All of these are covered by the OpenAPI specification.

## 2. This marketing site

`https://www.skillhive.com` exposes **no public API**. The sign-in page at
`/auth` is a private CMS login for Intunex staff (blog and user guides) and is
not an integration surface. Agents should ignore it.

## 3. OAuth / OIDC — deliberately absent

`/.well-known/oauth-authorization-server` and
`/.well-known/openid-configuration` intentionally return **404**. Skillhive does
not operate an OAuth 2.0 authorization server, and publishing RFC 8414 metadata
for a server that does not exist would break strict clients. Use the bearer-JWT
flow in section 1.

`/.well-known/oauth-protected-resource` is published as a resource descriptor
only; its `authorization_servers` array is empty by design.

## Data protection

Skillhive is GDPR-native and hosted in the EU. See
<https://www.skillhive.com/privacy> and
<https://www.skillhive.com/alihankkijat> for processing details.