{ "openapi" : "3.0.1", "info" : { "title" : "OAuth 2.0 API", "description" : "The OAuth 2.0 API exposes the resources for third parties to connect to ING APIs using the OAuth 2.0 protocol for authentication and authorization. This API supports the \"client credentials\", \"authorization code\" and \"refresh token\" grant types. Subscription to this API is only required when the Authorization Grant code flow is required for your application. The other supported [OAuth 2.0](https://tools.ietf.org/html/rfc6749) flows can be used without subscription.", "contact" : { "name" : "ING Developer Portal", "url" : "https://developer.ing.com", "email" : "developerportal@ing.com" }, "version" : "2.3.5" }, "servers" : [ { "url" : "https://api.ing.com/" } ], "paths" : { "/oauth2/token" : { "post" : { "summary" : "Retrieve an application or customer access token, or refresh an access token", "description" : "\nThis endpoint allows requesting an access token for one of the flows below:\n\n## Client Credentials (registered in the ING Developer portal)\nFor authenticating your application and retrieving an application access token.\nRequired request parameters:\n- grant_type=client_credentials\n- scope (optional): If not provided, all the subscribed scopes will be returned\n\n## Client Credentials (without pre-registration using eIDAS/OBIE certificates supporting PSD2)\nFor authenticating your application and retrieving an application access token without pre-registration in the ING Developer portal using eIDAS/OBIE certificates supporting PSD2. This flow will automatically subscribe your application to the allowed ING APIs based on the PSD2 roles in the certificate. The scopes in the application access token are based on the PSD2 roles.\nRequired request parameters:\n- grant_type=client_credentials\n- TPP-Signature-Certificate: PSD2 compliant Qualified Electronic Seal Certificate (QSealC)\n\n## Authorization Code\nFor exchanging the authorization code for a customer access token. \nRequired request parameters:\n- grant_type=authorization_code\n- code (required)\n- redirect_uri (optional)\n\n## Refresh Token\nFor exchanging a refresh token for a new customer access token.\nRequired request parameters:\n- grant_type=refresh_token\n- refresh_token (required)\n \n ## Access tokens and message signing\n Most of our APIs require a combination of TLS and and request signing to verify the identity of the sender of the message and to verify that the message was not tampered with during transit. While some APIs are currently using HTTP Signatures, ING is standardizing on the use of JWS for message signing as per the Open Banking Europe specification.\n\n [Want to learn more about the JSON Web Signature specification for Open Banking?](https://www.openbankingeurope.eu/media/2096/obe-json-web-signature-profile-for-open-banking.pdf)\n\n [Want to learn more about the HTTP Signature specification?](https://tools.ietf.org/html/draft-cavage-http-signatures-10)\n\n ## Why is this important when requesting an access token?\n An access token requested using the HTTP Signature approach can only be used for consuming APIs that use HTTP Signatures for message signing. An access token requested using the Mutual TLS approach can only be used for consuming APIs that rely on JWS and / or Mutual TLS.\n ## JSON Web Signature (JWS) and Mutual TLS (mTLS)\n In addition to the required parameters mentioned above for the different authentication flows (Client Credentials, Authorization code and Refresh token), the following additional request parameters are required for use with JWS and mTLS :\n - client_id (required) \n ## HTTP Signature `DEPRECATED`\n In addition to the required parameters mentioned above for the different authentication flows (Client Credentials, Authorization code and Refresh token), the following additional request parameters are required for use with HTTP Signature:\n - Authorization (required)\n - Digest (required)\n", "operationId" : "getAccessTokenUsingPOST", "parameters" : [ { "name" : "Authorization", "in" : "header", "description" : "Optional field when requesting an access token for the 'client_credentials' grant type that will be used for APIs that are using mTLS and/or JWS Signature.\n\n Required field when requesting an access token for the 'client_credentials' grant type that will be used for APIs that are using HTTP Signature. In that case it is used for the the signature authentication scheme as defined in https://tools.ietf.org/html/draft-cavage-http-signatures-10. ING requires the headers '(request-target) date digest', the client ID is used as keyID, and the algorithm is 'rsa-sha256' or 'ecdsa-sha256', 'ecdsa-sha384', 'ecdsa-sha512'.\n\n Required field for the 'authorization_code' and 'refresh_token' grant type. In that case it is used for the bearer authentication scheme with the application access token.", "schema" : { "type" : "string" } }, { "name" : "Signature", "in" : "header", "description" : "Optional field when using the 'client_credentials' grant type, or when requesting an access token that will be used for APIs that are using mTLS and/or JWS Signature.\n\n Required field when using the 'authorization_code' or 'refresh_token' grant type when using HTTP Signature. In this case the Signature header is used for HTTP Signature as defined in https://tools.ietf.org/html/draft-cavage-http-signatures-10. ING requires the headers '(request-target) date digest', and the algorithm is 'rsa-sha256' or 'ecdsa-sha256', 'ecdsa-sha384', 'ecdsa-sha512'.", "schema" : { "type" : "string" } }, { "name" : "Date", "in" : "header", "description" : "The current date in the HTTPs standard Date header format (see RFC7231: https://tools.ietf.org/html/rfc7231#section-7.1.1.2).\n\n Optional field when using mTLS and/or JWS Signature.\n\n Required field when using HTTP Signature.", "schema" : { "type" : "string" } }, { "name" : "Digest", "in" : "header", "description" : "The SHA-256 hash value of the request body encoded in Base64. If the body is empty, it should be the SHA-256 value of the empty string.\n\n Optional field when using mTLS and/or JWS Signature.\n\n Required field when using HTTP Signature.", "schema" : { "type" : "string" } }, { "name" : "TPP-Signature-Certificate", "in" : "header", "description" : "If your application is not registered in the ING Developer portal, you can add the PSD2 compliant Qualified Electronic Seal Certificate (QSealC) which you used for the signature in the client credentials grant type. The certificate (PEM format) needs to be the Base64 encoded", "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/x-www-form-urlencoded" : { "schema" : { "required" : [ "grant_type" ], "properties" : { "client_id" : { "type" : "string", "description" : "The client_id for your registered application in the ING Developer portal.\n\n Required field when requesting an access token for the 'client_credentials' grant type that will be used for APIs that are using mTLS and/or JWS Signature.\n\n Optional field in all other cases, eg when requesting an access token that will be used for APIs that are using HTTP Signature, or when using the 'authorization_code' or 'refresh_token' grant type." }, "grant_type" : { "type" : "string", "description" : "OAuth 2.0 grant type", "enum" : [ "client_credentials", "authorization_code", "refresh_token" ] }, "scope" : { "type" : "string", "description" : "Requested scopes in the 'client_credentials' grant type. Optional field, if not provided the registered scopes will be used. Scopes are delimited by a space and the complete field should be application/x-www-form-urlencoded" }, "code" : { "type" : "string", "description" : "Required in the 'authorization_code' grant type, value is the recieved authorization code from the authorization request" }, "redirect_uri" : { "type" : "string", "description" : "Required in the 'authorization_code' grant type, the 'redirect_uri' parameter as included in the authorization request." }, "refresh_token" : { "type" : "string", "description" : "Required in the 'refresh_token' grant type, the refresh token issued." } } } } }, "required" : true }, "responses" : { "200" : { "description" : "OK Returns an access token, and optionally a refresh token and JSON Web Key set.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/TokenResponse" } } } }, "400" : { "description" : "Bad Request - The request was invalid", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Error" } } } }, "500" : { "description" : "Internal Server Error - The server encountered an unexpected internal error." } } } }, "/oauth2/authorization-server-url" : { "get" : { "summary" : "Retrieve the ING Authorization server URL with a specific request identifier", "description" : "This endpoint stores the received data and returns a object/body with a location property containing the authorize URI with a specific reference ID for request identification. In case of error the API returns the error description.", "operationId" : "authorizationServerUrlUsingGET", "parameters" : [ { "name" : "Authorization", "in" : "header", "description" : "Application access token (bearer) received in the Client Credentials grant flow", "required" : true, "schema" : { "type" : "string" } }, { "name" : "Signature", "in" : "header", "description" : "Signature header as defined in https://tools.ietf.org/html/draft-cavage-http-signatures-10. ING requires the headers '(request-target) date digest', and the algorithm is 'rsa-sha256' or 'ecdsa-sha256', 'ecdsa-sha384', 'ecdsa-sha512'.", "required" : true, "schema" : { "type" : "string" } }, { "name" : "Date", "in" : "header", "description" : "The current date in the HTTPs standard Date header format (see RFC7231: https://tools.ietf.org/html/rfc7231#section-7.1.1.2)", "required" : true, "schema" : { "type" : "string" } }, { "name" : "Digest", "in" : "header", "description" : "The SHA-256 hash value of the requests body encoded in Base64. If the body is empty, it should be the SHA-256 value of the empty string.", "required" : true, "schema" : { "type" : "string" } }, { "name" : "redirect_uri", "in" : "query", "description" : "URI where user is redirected to after authorization. Only required when your application is not registered in the ING Developer portal, and your are using PSD2 compliant eIDAS/OBIE certificates", "schema" : { "type" : "string" } }, { "name" : "scope", "in" : "query", "description" : "List of scopes for which an authorization request is asked, separated by space. Must not be empty and it is validated based on the subscriptions of your API.", "required" : true, "schema" : { "type" : "string" } }, { "name" : "country_code", "in" : "query", "description" : "Country Code 2 letter value(ISO 3166-1). The country code is optional, and allows you to redirect you user to a specific ING country login page.", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "OK Response body containing the authorisation url where you can redirect your user to, to obtain the authorization for the requested scopes.", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/AuthorizationURLResponse" } } } }, "400" : { "description" : "Bad Request", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Error" } } } }, "500" : { "description" : "Internal Server Error - The server encountered an unexpected internal error." } }, "security" : [ { "ING-Application-Security" : [ "granting" ] } ] } }, "/oauth2/token/revoke" : { "post" : { "summary" : "Revoke a customer refresh token.", "description" : "This endpoint is used to revoke an existing token from a client.", "operationId" : "revokeRefreshTokenUsingPOST", "parameters" : [ { "name" : "Authorization", "in" : "header", "description" : "Application access token as bearer token", "required" : true, "schema" : { "type" : "string" } }, { "name" : "Signature", "in" : "header", "description" : "Optional field when when using an access token that was acquired through using mTLS and/or JWS Signature.\n\n Required field when using HTTP Signature for message integrity. In this case the Signature header is used for HTTP Signature as defined in https://tools.ietf.org/html/draft-cavage-http-signatures-10. ING requires the headers '(request-target) date digest', and the algorithm is 'rsa-sha256' or 'ecdsa-sha256', 'ecdsa-sha384', 'ecdsa-sha512'.", "schema" : { "type" : "string" } }, { "name" : "Date", "in" : "header", "description" : "The current date in the HTTPs standard Date header format (see RFC7231: https://tools.ietf.org/html/rfc7231#section-7.1.1.2).\n\n Optional field when using mTLS and/or JWS Signature.\n\n Required field when using HTTP Signature.", "schema" : { "type" : "string" } }, { "name" : "Digest", "in" : "header", "description" : "The SHA-256 hash value of the request body encoded in Base64. If the body is empty, it should be the SHA-256 value of the empty string.\n\n Optional field when using mTLS and/or JWS Signature.\n\n Required field when using HTTP Signature.", "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/x-www-form-urlencoded" : { "schema" : { "required" : [ "token" ], "properties" : { "token" : { "type" : "string", "description" : "The customer refresh token that needs to be revoked." }, "token_type_hint" : { "type" : "string", "description" : "Token type", "enum" : [ "refresh_token" ] } } } } }, "required" : true }, "responses" : { "200" : { "description" : "OK" }, "400" : { "description" : "Bad Request", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/Error" } } } }, "500" : { "description" : "Internal Server Error - The server encountered an unexpected internal error." } } } } }, "components" : { "schemas" : { "AuthorizationURLResponse" : { "type" : "object", "properties" : { "location" : { "type" : "string", "example" : "https://myaccount.ing.com/granting/dc53ca2d9681cbd355ae697694dae3f9736b45854edbf96d0a23a186b3f8011b/NL", "x-ing-type" : "string" } } }, "TokenResponse" : { "required" : [ "access_token", "expires_in", "scope", "token_type" ], "type" : "object", "properties" : { "access_token" : { "type" : "string", "example" : "eyJhbGciOiJkaXIiLCJlbmMiOi....", "x-ing-type" : "string" }, "expires_in" : { "type" : "integer", "example" : 900, "x-ing-type" : "integer" }, "scope" : { "type" : "string", "example" : "scope1 scope2", "x-ing-type" : "string" }, "token_type" : { "type" : "string", "example" : "Bearer", "x-ing-type" : "string" }, "refresh_token" : { "type" : "string", "example" : "eyJhbGciOiJkaXIiLCJlbmMiOi....", "x-ing-type" : "string" }, "refresh_token_expires_in" : { "type" : "integer", "example" : 3600, "x-ing-type" : "integer" }, "client_id" : { "type" : "string", "example" : "dc46e4b8-70aa-4da4-b74a-a2576680f004", "x-ing-type" : "string" }, "keys" : { "minItems" : 1, "type" : "array", "description" : "ING public key in JSON Web Key Set standard format (https://tools.ietf.org/html/rfc7517).", "items" : { "$ref" : "#/components/schemas/jsonWebKeySet" }, "x-ing-type" : "array" } } }, "Error" : { "required" : [ "message" ], "type" : "object", "properties" : { "message" : { "type" : "string", "x-ing-type" : "string" } } }, "jsonWebKeySet" : { "type" : "object", "properties" : { "kty" : { "type" : "string", "description" : "The key type", "example" : "RSA", "x-ing-type" : "string" }, "alg" : { "type" : "string", "description" : "The algorithm for the key", "example" : "RS256", "x-ing-type" : "string" }, "use" : { "type" : "string", "description" : "How the key was meant to be used", "example" : "sig", "x-ing-type" : "string" }, "kid" : { "type" : "string", "description" : "The unique identifier for the key", "x-ing-type" : "string" }, "n" : { "type" : "string", "description" : "The modulus for a standard pem", "x-ing-type" : "string" }, "e" : { "type" : "string", "description" : "The exponent for a standard pem", "x-ing-type" : "string" }, "x5t" : { "type" : "string", "description" : "The thumbprint of the x.509 cert (SHA-1 thumbprint)", "x-ing-type" : "string" }, "x5c" : { "type" : "array", "description" : "The x509 certificate chain", "items" : { "type" : "string", "x-ing-type" : "string" }, "x-ing-type" : "array" } }, "description" : "ING's current public key certificate encoded as a JSON Web Key SET (JWKS)" } }, "securitySchemes" : { "ING-Application-Security" : { "type" : "oauth2", "flows" : { "clientCredentials" : { "tokenUrl" : "https://api.ing.com/oauth2/token", "scopes" : { "granting" : "Required to start the \"granting\" flow for an ING customer." } } } } } }, "x-ing-guidelines-version" : 1 }