API docs by Redocly

Auth API (1.0)

Download OpenAPI specification:Download

Note:

Starting from March 15, 2024, authorization via Basic Auth will be discontinued for users with 2-Factor Authentication enabled.

For users:

  • With 2-Factor Authentication disabled for their accounts, we recommend users to enable 2-FA to improve security.
  • With 2-Factor Authentication enabled for their accounts, we recommend requesting token authorization through the Token Manager in the Data Center Designer (DCD). The Token Manager allows users to create, list, and delete tokens based on the defined Time To Live (TTL). This transition ensures a secure and hassle-free authorization process for enhanced account security.
  • IONOS' APIs and SDKs support users to authenticate using Basic Authentication which will be available until the end of this year.

If you have 2-Factor Authentication enabled, then you are no longer allowed to create or delete tokens using Token Management APIs. You can use the Token Manager in the Data Center Designer (DCD) to create or delete tokens.

Use the Auth API to manage tokens for secure access to IONOS Cloud APIs (Auth API, Cloud API, Reseller API, Activity Log API, and others).

tokens

Everything about tokens

Create new tokens

Users can generate new tokens (JWT or JSON Web Token). By default, new tokens are linked to the user’s contract. Users with multiple contracts must provide the contract number, for which the token is generated, in the X-Contract-Number header; otherwise, an error response is returned.

To access this endpoint, 'Basic Authentication' or 'Token Authentication' tokens with valid credentials must be encapsulated in the header, by users with one or with multiple contracts.

Note:

From March 15, 2024, users with 2-Factor Authentication enabled must generate new tokens using 2FA-secured tokens through DCD in the Token Manager. Tokens generated this way will not automatically inherit the 2FA-secured property.

The response will contain a newly-generated token for accessing any IONOS Cloud APIs (Auth API, Cloud API, Reseller API, Activity Log API, and others). The token can be used to access the APIs without providing the contract number in the `X-Contract-Number` header, by users with one or with multiple contracts. However, a valid contract number must be provided in the `X-Contract-Number` header to access the Auth API. By default, generated access tokens will expire after one year (subject to change).
Authorizations:
BasicAuthenticationTokenAuthentication
query Parameters
ttl
integer <int32> [ 60 .. 31536000 ]
Default: 31536000

The maximum time that the access token will be valid for use within the application in seconds.

header Parameters
X-Contract-Number
integer <int32>

Users with multiple contracts must provide the contract number, for which the token is generated.

Responses

Response samples

Content type
application/json
{
  • "token": "string"
}

List all tokens

List the details of all tokens, generated by the user. To access this endpoint, 'Basic Authentication' or 'Token Authentication' tokens with valid credentials must be encapsulated in the header. Users with multiple contracts must also provide a valid contract number in the X-Contract-Number header.

Authorizations:
BasicAuthenticationTokenAuthentication
header Parameters
X-Contract-Number
integer <int32>

Users with multiple contracts must provide the contract number, for which the token is generated.

Responses

Response samples

Content type
application/json
{
  • "tokens": [
    ]
}

Delete tokens by criteria

Delete one or multiple tokens by the required criteria parameter values: ALL, EXPIRED and CURRENT. With parameter values ALL and EXPIRED, 'Basic Authentication' or 'Token Authentication' tokens with valid credentials must be encapsulated in the header.

Note:

From March 15, 2024, users with 2-Factor Authentication must use 2FA-secured tokens to delete existing tokens. Token deletion can only be performed through DCD in the Token Manager.
With value CURRENT, only the 'Token Authentication' with valid credentials is required. Users with multiple contracts must also provide a valid contract number in the X-Contract-Number header.

Authorizations:
BasicAuthenticationTokenAuthentication
query Parameters
criteria
required
string

Delete tokens by criteria EXPIRED, ALL, or CURRENT. The tokens are deleted for the specified contract.

header Parameters
X-Contract-Number
integer <int32>

Users with multiple contracts must provide the contract number, for which the token is generated.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Get tokens by Key ID

Retrieve the details for a token by the Key ID (tokenId). To access this endpoint, 'Basic Authentication' or 'Token Authentication' tokens with valid credentials must be encapsulated in the header. Users with multiple contracts must also provide a valid contract number in the X-Contract-Number header.

Authorizations:
BasicAuthenticationTokenAuthentication
path Parameters
tokenId
required
string

The Key ID of the token (can be retrieved from the header section of the token).

header Parameters
X-Contract-Number
integer <int32>

Users with multiple contracts must provide the contract number, for which the token is generated.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "href": "string",
  • "createdDate": "string",
  • "expirationDate": "string"
}

Delete tokens

Delete a token by Key ID (tokenId). To access the endpoint, 'Basic Authentication' or 'Token Authentication' tokens with valid credentials must be encapsulated in the header.

Note:

From March 15, 2024, users with 2-Factor Authentication must use 2FA-secured tokens to delete existing tokens. Token deletion can only be performed through DCD in the Token Manager.

Users with multiple contracts must also provide a valid contract number in the `X-Contract-Number` header.
Authorizations:
BasicAuthenticationTokenAuthentication
path Parameters
tokenId
required
string

The Key ID of the token (can be retrieved from the header section of the token).

header Parameters
X-Contract-Number
integer <int32>

Users with multiple contracts must provide the contract number, for which the token is generated.

Responses

Response samples

Content type
application/json
{
  • "success": true
}