{"openapi":"3.0.0","x-samples-languages":["curl"],"info":{"title":"Identity API 1.0","version":"v2.0","x-hugo-values":{"tags":["api"],"categories":["OAuth 2.0","Token exchange"],"public":true,"weight":50},"description":"This specification explains how to get access to Karhoo API from third-party apps.\nIt is a complementary part of the **[Authentication API v1.0](#auth)** which was primarily designed to obtain credentials required for accessing Karhoo API in backend-to-backend communication scenarios.\nThe following specification expands it further and addresses use cases of third-party web and mobile applications (clients) attempting to access Karhoo API. Furthermore, it enables federated identities (delegation scenarios) where users can be registered within external authentication systems rather than the Karhoo platform itself.\nThis specification is compliant with the [OAuth 2.0 Authorization Framework spec](https://tools.ietf.org/html/rfc6749)."},"servers":[{"url":"https://sso.sandbox.karhoo.com","description":"Sandbox"},{"url":"https://sso.karhoo.com","description":"Production"},{"url":"https://sso.stg.karhoo.net","description":"Staging"}],"paths":{"/oauth/v2/authorize":{"get":{"tags":["OAuth 2.0"],"summary":"Authorize endpoint","description":"The authorization endpoint is used to interact with the user and obtain an authorization grant (code). This endpoint should be visited from a browser as it displays a page with a login form where users can enter their credentials.\n\nIn order to use this endpoint your application must be registered within Karhoo auth service as a valid client (assigned with a `client_id` and with its `redirect_uri` whitelisted).\n\nUpon successful authentication the user will be redirected back to the `redirect_uri` with an authorization code passed as a query parameter (e.g. `https://your-app.example.com/oauth/callback?code=eBd...sd0`). The `code` should be further used on [/oauth/v2/token](#post_oauth-v2-token) endpoint to obtain Karhoo access token which completes the 2-legged authorization process.\n\nThis endpoint is compliant with the [OAuth 2.0 Authorization Framework spec](https://tools.ietf.org/html/rfc6749#section-3.1).","parameters":[{"in":"query","name":"client_id","required":true,"description":"An identifier of your app registered within Karhoo auth service as a valid client.","example":"your-app-id","schema":{"type":"string"}},{"in":"query","name":"redirect_uri","required":true,"description":"A URI the user is going to be redirected into upon a successful authentication with an authorization code\n(must be whitelisted within Karhoo auth service).","schema":{"type":"string"},"example":"https://your-app.example.com/oauth/callback"},{"in":"query","name":"scope","required":true,"schema":{"type":"string"},"description":"A space-separated list of scopes requested access token should be issued with. This value is typically set to `openid profile email phone https://karhoo.com/traveller`.","example":"openid profile email phone https://karhoo.com/traveller"},{"in":"query","name":"response_type","required":true,"example":"code","schema":{"type":"string","enum":["code"]}}],"responses":{"200":{"description":"An HTML-based login page"}}}},"/oauth/v2/token":{"post":{"tags":["OAuth 2.0"],"summary":"Token endpoint","description":"The token endpoint is used in third-party apps to obtain Karhoo access tokens by presenting its authorization grant or a refresh token (the prerequisite for using this endpoint is being in possession of either an authorization code or a refresh token).\n**Authorization code**\nPrimary purpose of this endpoint is to finish the 2-legged authorization process initiated from the [/oauth/v2/authorize](#get_oauth-v2-authorize) endpoint. The token endpoint should be called with `grant_type=authorization_code` and the `code` received as a query parameter to your `redirect_uri`.\n**Refreshing the token**\nSecondary purpose of this endpoint is to refresh expired access tokens. When an access token expires, the token endpoint should be called with `grant_type=refresh_token` and the `refresh_token` obtained previously from either the authorization code flow or the token exchange flow. This allows you to obtain a new access token without being forced to reauthenticate with your username and password/an external token.\n\nIn order to use this endpoint your application must be registered within Karhoo auth service as a valid client (assigned with a `client_id`).\n\nThis endpoint is compliant with the [OAuth 2.0 Authorization Framework spec](https://tools.ietf.org/html/rfc6749#section-3.2).","security":[{"basicAuth":[]}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"client_id":{"description":"An identifier of your app registered within Karhoo auth service as a valid client.","type":"string"},"grant_type":{"description":"An authorization grant type.","type":"string","enum":["refresh_token","authorization_code"],"example":"refresh_token"},"refresh_token":{"type":"string","description":"A refresh token (used only when `grant_type = refresh_token`).","example":"6c1e8e5e-1f15-5c00-96e6-3a380d071e2f"},"code":{"type":"string","description":"An OAuth2 authorization code (used only when `grant_type = authorization_code`)."},"redirect_uri":{"type":"string","description":"An OAuth2 redirect URI (used only when `grant_type = authorization_code`)."}},"required":["client_id","grant_type"]}}}},"responses":{"200":{"description":"Token successfully refreshed","content":{"application/json":{"schema":{"type":"object","properties":{"token_type":{"type":"string","description":"The type of the token issued.","example":"bearer"},"access_token":{"description":"The access token issued by the authorization server.","type":"string","example":"eyJhb...Qssw5c"},"expires_in":{"type":"number","description":"The lifetime in seconds of the access token.","example":1800},"refresh_token":{"type":"string","description":"The refresh token issued by the authorization server.","example":"1b8af187-fcda-411c-9ca2-d61749fafb68"},"refresh_expires_in":{"type":"number","description":"The lifetime in seconds of the refresh token.","example":31622400},"scope":{"type":"string","description":"A space-separated list of scopes requested access token should be issued for.","example":"openid profile email phone https://karhoo.com/traveller"}}}}}},"400":{"description":"Bad request, invalid grant or token is missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"invalid_grant"},"error_code":{"type":"string","example":"invalid_grant"}}}}}}}}},"/oauth/v2/userinfo":{"get":{"tags":["OAuth 2.0"],"summary":"Getting user details","description":"The user info endpoint returns claims about the authenticated end-user. In order to get user details, the caller needs to send a valid access token representing the user.\n\nDepending on the granted scopes, the endpoint will return the mapped claims (see sample response for most commonly used user claims).\n\nThis endpoint is compliant with the [OpenID Connect Core 1.0 spec](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo).","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"User details successfully obtained","content":{"application/json":{"schema":{"type":"object","properties":{"sub":{"description":"A unique user identifier within Karhoo platform.","type":"string","example":"6c1e8e5e-1234-1234-1234-3a380d071e2f"},"upstream":{"type":"object","description":"A set of partner specific claims","properties":{"sub":{"description":"A unique user identifier within partner's platform.","type":"string","example":"1234567890"}}},"primary_organisation_id":{"type":"string","example":"7cedfe1d-a20c-4311-9043-2984f4e8eda4"},"client_id":{"type":"string","description":"The unique identifier of the app the authorization was initiated from","example":"your-app-id"},"organisations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"7cedfe1d-a20c-4311-9043-2984f4e8eda4"},"name":{"type":"string","example":"YourOrganisationName"},"roles":{"type":"array","items":{"type":"string","example":"MOBILE_USER"}}}}},"scope":{"type":"string","description":"A space-separated list of scopes the requested access token should be issued with.","example":"openid profile email phone https://karhoo.com/traveller"},"loyalty_cards":{"type":"array","description":"A list of loyalty cards associated with the traveller (only when available).","items":{"type":"object","properties":{"number":{"type":"string","example":"269281223464243"}}}},"given_name":{"type":"string","description":"First name","example":"John"},"family_name":{"type":"string","description":"Last name","example":"Doe"},"email":{"type":"string","description":"Email","example":"john.doe@karhoo.com"},"phone_number":{"type":"string","description":"Phone number in E.164 format","example":"+15005550006"},"locale":{"type":"string","description":"End-User's locale in BCP47 [RFC5646] format","example":"en"}}}}}},"401":{"description":"Wrong token provided.","content":{"application/json":{"schema":{"type":"object","properties":{"error_code":{"enum":["invalid_token"],"example":"invalid_token"}}}}}}}}},"/oauth/v2/revoke":{"post":{"tags":["OAuth 2.0"],"summary":"Revoking issued tokens","description":"The revocation endpoint gives possibility to invalidate the actual token and, if applicable, other tokens based on the same authorization grant.\n\nFrom an end-user's perspective, tokens are often used as a premise of users logged into a certain site or application. This revocation mechanism allows to invalidate its tokens if the end-user logs out, changes identity, or uninstalls the respective application. Notifying the authorization server that the token is no longer needed allows the authorization server to clean up data associated with that token (e.g., session data) and the underlying authorization grant.  This behavior prevents abuse of abandoned tokens of which the end-user is not aware anymore.\n\nIn order to use this endpoint your application must be registered within Karhoo auth service as a valid client (assigned with a `client_id`).\n\nThis endpoint is compliant with the [OAuth 2.0 Token Revocation spec](https://tools.ietf.org/html/rfc7009).","security":[{"basicAuth":[]}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"client_id":{"description":"An identifier of your app registered within Karhoo auth service as a valid client.","type":"string"},"token":{"type":"string","description":"The token that the client wants to get revoked (typically a refresh token).","example":"6c1e8e5e-1f15-5c00-96e6-3a380d071e2f"},"token_type_hint":{"type":"string","description":"A hint about the type of the token submitted for revocation.","example":"refresh_token","enum":["refresh_token","access_token"]}},"required":["client_id","token","token_type_hint"]}}}},"responses":{"200":{"description":"Token revoked succesfuly"},"401":{"description":"Bad request, invalid grant or token is missing","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"invalid_client"}}}}}}}}},"/oauth/v2/token-exchange":{"post":{"tags":["Token exchange"],"summary":"Authenticating with third-party tokens","description":"The token exchange endpoint allows external authentication systems to be integrated with Karhoo platform. This effectively means externally authenticated users can be authorized as Karhoo platform users.\n\nA prerequisite for this flow is a third-party application possessing a proof of user being authenticated within an external authentication system in form of a string token. This token represents the identity of the party on behalf of whom Karhoo access token should be issued.\n\nThis flow involves a backend integration between your authentication system and Karhoo’s authentication system to map and manage user claims. In order to use it, your application must be registered within Karhoo auth service as a valid client (assigned with a `client_id`).\n\nMoreover, you need to provide more details on how Karhoo auth service can use your tokens to extract/obtain user details such as: first name, last name, email, phone and locale. (typical scenarios are: external tokens are self-contained tokens (JWTs) or an additional user details endpoint is provided).","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"client_id":{"description":"An identifier of your app registered within Karhoo auth service as a valid client.","type":"string"},"token":{"description":"An external token (signed JWT or opaque token) as a proof of user being authenticated within an external authentication system","type":"string"},"scope":{"description":"A space-separated list of scopes requested access token should be issued for. This value is typically set to `openid profile email phone https://karhoo.com/traveller`.","type":"string","example":"openid profile email phone https://karhoo.com/traveller"}},"required":["client_id","token","scope"]}}}},"responses":{"200":{"description":"Token successfully exchanged","content":{"application/json":{"schema":{"type":"object","properties":{"token_type":{"type":"string","description":"The type of the token issued.","example":"bearer"},"access_token":{"description":"The access token issued by the authorization server.","type":"string","example":"eyJhb...Qssw5c"},"expires_in":{"type":"number","description":"The lifetime in seconds of the access token.","example":1800},"refresh_token":{"type":"string","description":"The refresh token issued by the authorization server.","example":"1b8af187-fcda-411c-9ca2-d61749fafb68"},"refresh_expires_in":{"type":"number","description":"The lifetime in seconds of the refresh token.","example":31622400},"scope":{"type":"string","description":"A space-separated list of scopes requested access token should be issued for.","example":"openid profile email phone https://karhoo.com/traveller"}}}}}},"400":{"description":"Wrong request format, e.g. missing or duplicated parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error_code":{"enum":["invalid_input"],"example":"invalid_input"}}}}}},"401":{"description":"Custom token validation failed or wrong client configuration e.g. token exchange is disabled.","content":{"application/json":{"schema":{"type":"object","properties":{"error_code":{"enum":["configuration_error","authentication_failed"],"example":"authentication_failed"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error_code":{"enum":["token_issuance_error"],"example":"token_issuance_error"}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"basicAuth":{"type":"http","scheme":"basic"}}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}