{"openapi":"3.0.2","info":{"title":"Access Token using mTLS authentication","version":"1.0.0","description":"Request mTLS access token that identifies your identity\nThe term \"realm\" is now known as \"organization\" or \"org\".\n"},"externalDocs":{"description":"The developer guide and related API references are available here.","url":"https://www.here.com/docs/category/identity-and-access-management"},"servers":[{"url":"https://mtls.account.api.here.com"}],"tags":[{"name":"API for Access Token using mTLS authentication","description":"API for Access Token using mTLS authentication"}],"paths":{"/mtls/token":{"parameters":[{"$ref":"#/components/parameters/XCorrelationId"},{"$ref":"#/components/parameters/XRequestId"}],"post":{"tags":["API for Access Token using mTLS authentication"],"summary":"Request an access token that identifies your identity using mTLS authentication","operationId":"Access Token using mTLS authentication getMtlsOAuth2AccessToken","description":"Request an access token that identifies your identity.\n## **Grant Types:**\n\n### **mTLS Grant Type [mtls]**\n* **Request a HERE access token that identifies your identity by providing a X.509 TLS signed certificate from\na trusted Certificate Authority during the standard TLS handshake.**\n  - Use grant type - mtls\n  - An optional scope can be added to the request body to request a project scoped access token\n  - The provided X.509 mTLS certificate **MUST** be issued by a Certificate Authority registered and enabled\n    as a trusted mTLS Identity Provider\n  - The provided X.509 mTLS signed certificate identifies the access context in the third party's identity namespace\n    according to the subject mapping rules defined for the configured authenticator of the identity provider.\n  - The identity **MUST** already exist in the realm of the registered mTLS Identity Provider in order for\n    authentication to be successful.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MtlsRequestJson"},"example":{"grantType":"mtls","expiresIn":3600,"scope":"hrn:here:authorization::myorg:project/myproject"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/MtlsRequestForm"},"example":{"grant_type":"mtls","expires_in":3600,"scope":"hrn:here:authorization::myorg:project/myproject"}}}},"responses":{"200":{"description":"OK","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/XCorrelationId"},"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MtlsResponseJson"},"example":{"accessToken":"eyJhbGciOiJSUzUxMiIsImN0e...x1dEEtSlJ4eFBvOEREZzJyeVFHOU9pUkRvYVh6Z","tokenType":"bearer","expiresIn":3600,"scope":"hrn:here:authorization::myorg:project/myproject"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/MtlsResponseForm"},"example":{"access_token":"eyJhbGciOiJSUzUxMiIsImN0e...x1dEEtSlJ4eFBvOEREZzJyeVFHOU9pUkRvYVh6Z","token_type":"bearer","expires_in":3600,"scope":"hrn:here:authorization::myorg:project/myproject"}}}},"400":{"description":"See https://tools.ietf.org/html/rfc6749#section-5.2 for allowed error response error parameter values. An error has occurred.\n* 400200 - Received invalid data. See 'errorFields' for more information.\n  * errorFields.errorCode 400208: Not a number.\n  * errorFields.errorCode 400209: Value too small\n  * errorFields.errorCode 400290: Illegal grant type.\n  * errorFields.errorCode 400927: Scope is invalid.\n* 400981 -  Only one project scope allowed in token.\n","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/XCorrelationId"},"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rfc6749ErrorMessage"}}}},"401":{"description":"An error has occurred.\n","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/XCorrelationId"},"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}},"403":{"description":"An error has occurred.\n* 403109 - Client is not a member of the project.\n","headers":{"X-Correlation-ID":{"$ref":"#/components/headers/XCorrelationId"},"X-Request-ID":{"$ref":"#/components/headers/XRequestId"}}}}}}},"components":{"parameters":{"XCorrelationId":{"in":"header","name":"X-Correlation-ID","schema":{"type":"string"},"required":false,"description":"Correlates HTTP requests between a client and server. If not present in the incoming request, it will be generated. This header and value will be included in all loglines including access logs. It will also be propagated to downstream services and returned in the response.\n"},"XRequestId":{"in":"header","name":"X-Request-ID","schema":{"type":"string"},"required":false,"description":"The unique for the request, used to track this request within the service.  X-Request-ID value is NOT propagated to the downstream services.\n"}},"headers":{"XCorrelationId":{"schema":{"type":"string"},"required":false,"description":"The X-Correlation-ID for the request, used to track this request in the platform. X-Correlation-ID value is propagated throughout the platform."},"XRequestId":{"schema":{"type":"string"},"required":false,"description":"The unique id for the request, used to track this request within the service. X-Request-ID value is NOT propagated to the downstream services."}},"schemas":{"MtlsRequestForm":{"type":"object","required":["grant_type"],"properties":{"grant_type":{"type":"string","description":"Always \"mtls\" for this operation.  NOTE - \"client_credentials\" is supported as an alias for \"mtls\" for backwards compatibility.","enum":["mtls","client_credentials"],"example":"mtls"},"expires_in":{"type":"integer","example":3600,"description":"Number of seconds before token expires, must number zero or more.  Ignored if greater than default expiration of the application.\n"},"token_format":{"type":"string","example":"hN","enum":["hN","jwt","jwt+header","jws"],"description":"Supported token formats are hN, jwt, jwt+header and jws.\n* 'hN' produces a HERE proprietary-formatted access token.\n* 'jwt' produces a Nested JWT-formatted access token with a JWE enclosed in a JWS.\n* 'jwt+header' produces a Nested JWT-formatted access token with a JWE enclosed in a JWS with additional claims copied into the JOSE header.\n* 'jws' produces a JWS-formatted access token with a JWS Payload containing the *plaintext* JWT Claims Set.\n"},"scope":{"type":"string","description":"Requested scope of the access token. Must be an HRN identifying a project that the identified user has access to.\n","example":"hrn:here:authorization::myrealm:project/myproject"}}},"MtlsRequestJson":{"type":"object","required":["grantType"],"properties":{"grantType":{"type":"string","description":"Always \"mtls\" for this operation. NOTE - \"client_credentials\" is supported as an alias for \"mtls\" for backwards compatibility.","enum":["mtls","client_credentials"],"example":"mtls"},"expiresIn":{"type":"integer","example":3600,"description":"Number of seconds before token expires, must number zero or more. Ignored if greater than default expiration of the application.\n"},"tokenFormat":{"type":"string","enum":["hN","jwt","jwt+header","jws"],"example":"hN","description":"Supported token formats are hN, jwt, jwt+header and jws.\n* 'hN' produces a HERE proprietary-formatted access token.\n* 'jwt' produces a Nested JWT-formatted access token with a JWE enclosed in a JWS.\n* 'jwt+header' produces a Nested JWT-formatted access token with a JWE enclosed in a JWS with additional claims copied into the JOSE header.\n* 'jws' produces a JWS-formatted access token with a JWS Payload containing the *plaintext* JWT Claims Set.\n"},"scope":{"type":"string","description":"Requested scope of the access token. Must be an HRN identifying a project that the identified user has access to.\n","example":"hrn:here:authorization::myrealm:project/myproject"}}},"MtlsResponseJson":{"type":"object","properties":{"accessToken":{"type":"string","description":"The new client access token, identifying your service..","example":"eyJhbGciOiJSUzUxMiIsImN0e...x1dEEtSlJ4eFBvOEREZzJyeVFHOU9pUkRvYVh6Z"},"tokenType":{"type":"string","description":"Always \"bearer\" for this operation..","example":"Bearer"},"expiresIn":{"type":"integer","description":"Seconds until token expiration.","example":3600},"scope":{"type":"string","description":"Optional. The scope assigned to the access token.","example":"hrn:here:authorization::myrealm:project/myproject"}}},"MtlsResponseForm":{"type":"object","properties":{"access_token":{"type":"string","description":"The new client access token, identifying your service..","example":"eyJhbGciOiJSUzUxMiIsImN0e...x1dEEtSlJ4eFBvOEREZzJyeVFHOU9pUkRvYVh6Z"},"token_type":{"type":"string","description":"Always \"bearer\" for this operation..","example":"Bearer"},"expires_in":{"type":"integer","description":"Seconds until token expiration.","example":3600},"scope":{"type":"string","description":"Optional. The scope assigned to the access token.","example":"hrn:here:authorization::myrealm:project/myproject"}}},"Rfc6749ErrorMessage":{"type":"object","allOf":[{"$ref":"#/components/schemas/ErrorMessage"},{"$ref":"#/components/schemas/Rfc6749Extensions"}]},"Rfc6749Extensions":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"REQUIRED.  A single ASCII [USASCII] error code from the\nfollowing:\n\n- invalid_request\n               The request is missing a required parameter, includes an\n               unsupported parameter value (other than grant type),\n               repeats a parameter, includes multiple credentials,\n               utilizes more than one mechanism for authenticating the\n               client, or is otherwise malformed.\n\n- invalid_client\n               Client authentication failed (e.g., unknown client, no\n               client authentication included, or unsupported\n               authentication method).  The authorization server MAY\n               return an HTTP 401 (Unauthorized) status code to indicate\n               which HTTP authentication schemes are supported.  If the\n               client attempted to authenticate via the \"Authorization\"\n               request header field, the authorization server MUST\n               respond with an HTTP 401 (Unauthorized) status code and\n               include the \"WWW-Authenticate\" response header field\n               matching the authentication scheme used by the client.\n\n- invalid_grant\n               The provided authorization grant (e.g., authorization\n               code, resource owner credentials) or refresh token is\n               invalid, expired, revoked, does not match the redirection\n               URI used in the authorization request, or was issued to\n               another client.\n\n- unauthorized_client\n               The authenticated client is not authorized to use this\n               authorization grant type.\n\n- unsupported_grant_type\n               The authorization grant type is not supported by the\n               authorization server.\n- invalid_scope\n               The requested scope is invalid, unknown, malformed, or\n               exceeds the scope granted by the resource owner.\n\nValues for the \"error\" parameter MUST NOT include characters\noutside the set %x20-21 / %x23-5B / %x5D-7E.\n"},"error_description":{"type":"string","description":"OPTIONAL.  Human-readable ASCII [USASCII] text providing\nadditional information, used to assist the client developer in\nunderstanding the error that occurred.\nValues for the \"error_description\" parameter MUST NOT include\ncharacters outside the set %x20-21 / %x23-5B / %x5D-7E.\n"},"error_uri":{"type":"string","description":"OPTIONAL.  A URI identifying a human-readable web page with\ninformation about the error, used to provide the client\ndeveloper with additional information about the error.\nValues for the \"error_uri\" parameter MUST conform to the\nURI-reference syntax and thus MUST NOT include characters\noutside the set %x21 / %x23-5B / %x5D-7E.\n"}}},"ErrorMessage":{"type":"object","required":["title","status","code","cause","action","correlationId"],"example":{"title":"Input data failed validation","status":400,"code":"E110000","cause":"The input data in question does not meet validation rules","action":"Actionable instructions for the user.","correlationId":"6c1bce6d-d31f-4275-9d9f-6832d8ba2377"},"properties":{"title":{"type":"string","description":"Title of the error."},"status":{"type":"integer","minimum":0,"maximum":999,"description":"HTTP status code of error message."},"cause":{"type":"string","description":"The cause of the error."},"action":{"type":"string","description":"Actionable instructions for the user."},"correlationId":{"type":"string","description":"The Correlation ID for the request for tracking purposes."}}}}}}