OAuth flow

Initial redirect

If the Client supports PKCE, it creates and stores a PKCE challenge string (e.g. UUID). The challenge must be hashed using the following algorithm:

“plain text” → sha256 → base64 ‘Basic’ → UrlEncode

The Client uses the system browser to call

  GET /authorize

The following query parameters are recognized:

Parameter name	Parameter value	Mandatory	Description
redirect_uri	One of the redirect URIs given during registration	Yes	Used to redirect the browser to after login. Must be URL encoded.
response_type	“code”	Yes	Currently the only allowed grant type.
client_id	Unique client ID given during registration	Yes	Determines the client application.
state	Arbitrary string	No, but recommended	Opaque value used to maintain state between the request and the callback. Will be resent unmodified together with authentication code.
code_challenge	Encoded arbitrary string	Yes, if PKCE support has been acknowledged during registration. Strongly recommended.	A cr yptographically random string that is used to correlate the authorization request to the token request.
code_c hallenge_method	“S256”	Yes, if code_challenge is given	PKCE challenge hash method.
scope	Space delimited list of scope values. See below for possible values.	Yes for external clients like “Alexa”. No for internal clients and partners.	Determines the kind of resources to grant access to.
ui_locales	One of “de-DE”, “en-US”, “en-GB”, “en-CA”, “fr-FR”, “it-IT”, “es-ES”, “es-MX”	No; default determined by Accept-Language header, then TLD default.	Preferred User’s language for the consent and login pages.
market	Country code. One of DE, GB, FR, ES, IT, US, CA, MX	No; defaults to requested domain	Used to select the authentication endpoint domain. Does not affect language.
nonce	Arbitrary string	No	String value used to associate a Client session with an ID Token, and to mitigate replay attacks. Will be returned within the ID token.
prompt	One of “none” (never show login form), “login” (always show login form)	No; default is to show login form if not already authenticated	Specifies whether the User will be prompted for re- authentication.
display	One of “page”, “popup”, “touch”, “wap”	No; defaults to “page”	Specifies how login and consent pages should be shown to the User.
login_hint	Login name to be pre-filled in login form	No	Can be used to pre-fill username in login form. If login_hint ends with “.ionos.id”, suffix will be stripped silently, thus ” 12345.ionos.id” would be pre-filled as “12345”.

The following is a non-normative example HTTP 302 redirect response by the Client, which triggers the User Agent to make an Authentication Request to the Authorization Endpoint (with line wraps within values for display purposes only):

HTTP/1.1 302 Found
Location: https://id.ionos.de/authorize?
client_id=8F8092F5-D0BC-4703-AA39-32B5B339BA2C
&code_challenge=LCa0a2j_xo_5m0U8HTBBNBNCLXBkg7-g-YpeiGJm564
&code_challenge_method=S256
&nonce=some-nonce
&redirect_uri=https%3A%2F%2Fclient.example.org%2Foauth
&response_type=code
&state=some-state

The OAuth Service will handle the User’s login and consent procedure and redirect back to the given redirect URI. The Client parses the redirect’s query parameters and on success proceeds with the next step. The following query parameters will be given:

Parameter name	Parameter value	Mandatory	Description
code	Authorization code	Yes	Authorization code to be used for token request.
state	Arbitrary string	No	Client state, passed through unmodified if given in request.

Example

HTTP/1.1 302 Found
Location: http://client.example.org/oauth?
code=0af15b47-cb87-4a9c-854d-4eea9c82dede
&state=some-state

Token request

The Client calls

  POST /token

The call must be secured either by Basic Authentication using the Client ID and Client secret given during registration, or by passing both values as POST parameters. PUBLIC (untrusted) clients must pass only the Client ID as POST parameter. The following parameters will be recognized (Content-Type: application/x-www-form-urlencoded):

Parameter name	Parameter value	Mandatory	Description
grant_type	“auth orization_code”	Yes	Currently the only allowed value.
code	Authorization code	Yes	The authorization code retrieved by auth request.
redirect_uri	Redirect URI given on auth request	Yes	Must match the redirect URI given on auth request.
code_verifier	Plain text code challenge	Yes, if PKCE support has been acknowledged during registration.	PKCE challenge string given on auth request (not hashed).
device_name	Arbitrary string	No	May be used to describe the User’s device, e.g. “John’s phone”. May contain arbitrary characters, so urlencoded UTF-8 is expected.
client_id	Client ID	Yes, if client is untrusted (PUBLIC), otherwise no	Trusted (non PUBLIC) clients may POST their client ID and secret as an alternative to BasicAuth.
client_secret	Client secret	No	Trusted (non PUBLIC) clients may POST their client ID and secret as an alternative to BasicAuth.

The following shows an example of a token request. The parameter code_verifier indicates that PKCE is used.

POST /token HTTP/1.1
Host: id.ionos.de
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

grant_type=authorization_code
&code=0af15b47-cb87-4a9c-854d-4eea9c82dede
&redirect_uri=https%3A%2F%2Fclient.example.org%2Foauth
&code_verifier=foo

Upon successful server side verification the following JSON structure will be returned:

{
  "token_type":"Bearer",
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "expires_in":3600,
  "id_token":"abcd.efgh.ijkl"
}

“token_type” “Bearer” is the default OAuth token type. “access_token” is the OAuth access token which can be used to access IONOS Resource Servers. The “refresh_token” can be used to retrieve a new access token when the original token’s lifetime has expired. “expires_in” denotes the remaining token lifetime in seconds.

If scope “openid” had been given within the auth request, an OpenID Connect token will be returned as “id_token”. The value is a standard RS512 signed JSON Web Token which must be validated by the client (see below).

Refresh token request

When an access token has expired, the Client may retrieve a new one by calling

  POST /token

(again secured by Basic Authentication), passing the following parameters (Content-Type: application/x-www-form-urlencoded):

Parameter name	Parameter value	Mandatory	Description
grant_type	“refresh_token”	Yes
refresh_token	Refresh token	Yes	The valid refresh token retrieved together with original access token.

Upon successful server side verification the following JSON structure will be returned:

{
  "token_type":"Bearer",
  "access_token":"3ZWotnFZFEjr1zCsicMWpAA",
  "refresh_token":"uHav3JOkF0XG5Qx2TlKWIA",
  "expires_in":3600
}

Token revocation

When a token session is no longer needed, it can be revoked by calling

  POST /token

(secured by Basic Authentication) and passing either an access token or a refresh token as parameter (Content-Type: application/x-www-form-urlencoded):

Parameter name	Parameter value	Mandatory	Description
token	Access or refresh token	Yes	Access token or refresh token representing User session.

If the token is valid the OAuth Server will delete the entire session represented by that token.