List Ingresses
GET/v2/ingresses
API version
v2
Request method
GET
Operation ID
ingress-list-ingresses
Request
- projectIdstring
ID of the Project to list Ingresses for.
- certificateIdstring (uuid)
ID of the Certificate to list Ingresses for.
- hostnameSubstringstring (≤ 253 characters)
Substring of the hostnames to be retrieved.
- appInstallationIdstring
ID of the AppInstallation to list Ingresses for.
- containerIdstring (uuid)
ID of the Container to list Ingresses for.
- limitinteger (≥ 0)
The max count of resources to return in the list response.
- skipinteger
Number of items to skip. Should be multiple of
limit. - pageinteger (≥ 0)
Page to display.
skipandpageend up doing the same. If bothpageandskipare set, skip is used.
Responses
Response headers
- X-Pagination-Limitinteger
The limit used to select the resources for the response
- X-Pagination-Skipinteger
The number of skipped items
- X-Pagination-Pagenumber
The calculate page of the list response. Refer to parameters to learn more.
- X-Pagination-TotalCountinteger
The total amount of items available in the remote ressource. Use this value in combination with the limit to calculate the available pages.
Format
application/json
Description
OK
- Array[
- *object
- accessProtectionobject
Login protection of an Ingress: one identity provider for the hostname, enabled and configured per path.
- allPathsobject
Protects every path of the Ingress, also those added later; redirects stay reachable.
- passIdentityHeadersbooleanrequired
Whether the targets receive the identity of the logged-in user as request headers.
- rulesobjectrequired
Who may pass after logging in. A user needs to match one of the rules; at least one rule is set.
- allowAnyAuthenticatedUserbooleanrequired
Every user the provider authenticates may pass. Only with the OIDC provider.
- allowedEmailDomainsarray of string (idn-hostname)required
- Array[
- *string (idn-hostname)
]
- allowedEmailsarray of string (email)required
- Array[
- *string (email)
]
- projectMembersOnlybooleanrequired
Only members of the Ingress's Project may pass. Requires the mStudio provider.
- pathsarray of objectrequired
The protected paths. Paths not listed here are not protected, even if a parent path is. Empty if
allPathsis set.- Array[
- *object
- passIdentityHeadersbooleanrequired
Whether the target receives the identity of the logged-in user as request headers.
- pathstringrequired
- rulesobjectrequired
Who may pass after logging in. A user needs to match one of the rules; at least one rule is set.
- allowAnyAuthenticatedUserbooleanrequired
Every user the provider authenticates may pass. Only with the OIDC provider.
- allowedEmailDomainsarray of string (idn-hostname)required
- Array[
- *string (idn-hostname)
]
- allowedEmailsarray of string (email)required
- Array[
- *string (email)
]
- projectMembersOnlybooleanrequired
Only members of the Ingress's Project may pass. Requires the mStudio provider.
]
- providerone of 2 alternativesrequired
- Alternativeobject
Users log in with their mStudio account.
- mstudioobjectrequired
- Alternativeobject
Users log in with an external OpenID Connect provider. The client secret is never returned.
- oidcobjectrequired
- clientIdstringrequired
- issuerUrlstring (uri)required
- dnsValidationErrorsarray of string (one of: ERROR_UNSPECIFIED, ERROR_QUAD_A, ERROR_NO_A_RECORD, ERROR_ACME_CERTIFICATE_REQUEST_DEADLINE_EXCEEDED)required
A list of errors that occurred while validating the ingress's dns before requesting a certificate.
ERROR_QUAD_AandERROR_NO_A_RECORDare deprecated and no longer reported.- Array[
- *string (one of: ERROR_UNSPECIFIED, ERROR_QUAD_A, ERROR_NO_A_RECORD, ERROR_ACME_CERTIFICATE_REQUEST_DEADLINE_EXCEEDED)
]
- hostnamestring (idn-hostname)required
- idstring (uuid)required
- ipsobjectrequired
- v4array of string (ipv4)required
- Array[
- *string (ipv4)
]
- v6array of string (ipv6)required
- Array[
- *string (ipv6)
]
- isDefaultbooleanrequired
Whether this ingress is the default ingress or not. A default ingress is automatically created, it cannot be deleted. There can be only one default ingress per project.
- isDomainboolean
- isEnabledbooleanrequired
- ownershipobjectrequired
- txtRecordstring
- verifiedbooleanrequired
Whether the domain ownership is verified or not.
- pathsarray of objectrequired
A list of paths. The default path
/is always present and cannot be removed.- Array[
- *object
- pathstringrequired
- targetone of 4 alternativesrequired
- Alternativeobject
Redirect requests to this path to another URL
- urlstring (uri)required
The URL to which requests should be forwarded.
- Alternativeobject
Serve a specific app installation
- installationIdstring (uuid)required
The ID of an app installation within the same project to which requests should be forwarded.
- Alternativeobject
Serve a generic default page
- useDefaultPagebooleanrequired
Set this to
trueto serve a generic default site at this path.
- Alternativeobject
Forward requests to this path to a specific container.
- containerobjectrequired
- idstring (uuid)required
- portProtocolstring (docker-network-port)required
docker-compose port specification in format port/protocol (e.g. 8080/TCP)
]
- projectIdstring (uuid)required
- senderLoginProtectionboolean
If enabled, only mailboxes of the Ingress's Project may send emails from addresses of the Ingress and its SubIngresses. Only set on the root Ingress, as it covers all of its SubIngresses.
- tlsone of 2 alternativesrequired
- Alternativeobject
- acmebooleanrequired
Has to be
true, as ssl cannot be deactivated. - isCreatedbooleanrequired
- requestDeadlinestring (date-time)
- Alternativeobject
- certificateIdstring (uuid)required
]
Content-Type: application/json
[
{
"accessProtection": {
"allPaths": {
"passIdentityHeaders": true,
"rules": {
"allowAnyAuthenticatedUser": true,
"allowedEmailDomains": [
"example.com"
],
"allowedEmails": [
"ada@example.com"
],
"projectMembersOnly": true
}
},
"paths": [
{
"passIdentityHeaders": true,
"path": "/admin",
"rules": {
"allowAnyAuthenticatedUser": true,
"allowedEmailDomains": [
"example.com"
],
"allowedEmails": [
"ada@example.com"
],
"projectMembersOnly": true
}
}
],
"provider": {
"mstudio": {}
}
},
"dnsValidationErrors": [
"ERROR_UNSPECIFIED"
],
"hostname": "some-hostname.example",
"id": "f0f86186-0a5a-45b2-aa33-502777496347",
"ips": {
"v4": [
"string"
],
"v6": [
"string"
]
},
"isDefault": true,
"isDomain": true,
"isEnabled": true,
"ownership": {
"txtRecord": "string",
"verified": true
},
"paths": [
{
"path": "string",
"target": {
"url": "https://redirect-target.example"
}
}
],
"projectId": "f0f86186-0a5a-45b2-aa33-502777496347",
"senderLoginProtection": true,
"tls": {
"acme": true,
"isCreated": true,
"requestDeadline": "1985-10-26T01:21:00.000Z"
}
}
]
{
"items": {
"properties": {
"accessProtection": {
"additionalProperties": false,
"description": "Login protection of an Ingress: one identity provider for the hostname, enabled and configured per path.",
"properties": {
"allPaths": {
"additionalProperties": false,
"description": "Protects every path of the Ingress, also those added later; redirects stay reachable.",
"properties": {
"passIdentityHeaders": {
"description": "Whether the targets receive the identity of the logged-in user as request headers.",
"type": "boolean"
},
"rules": {
"additionalProperties": false,
"description": "Who may pass after logging in. A user needs to match one of the rules; at least one rule is set.",
"properties": {
"allowAnyAuthenticatedUser": {
"description": "Every user the provider authenticates may pass. Only with the OIDC provider.",
"type": "boolean"
},
"allowedEmailDomains": {
"items": {
"example": "example.com",
"format": "idn-hostname",
"type": "string"
},
"type": "array"
},
"allowedEmails": {
"items": {
"example": "ada@example.com",
"format": "email",
"type": "string"
},
"type": "array"
},
"projectMembersOnly": {
"description": "Only members of the Ingress's Project may pass. Requires the mStudio provider.",
"type": "boolean"
}
},
"required": [
"projectMembersOnly",
"allowedEmails",
"allowedEmailDomains",
"allowAnyAuthenticatedUser"
],
"type": "object"
}
},
"required": [
"rules",
"passIdentityHeaders"
],
"type": "object"
},
"paths": {
"description": "The protected paths. Paths not listed here are not protected, even if a parent path is. Empty if `allPaths` is set.",
"items": {
"additionalProperties": false,
"properties": {
"passIdentityHeaders": {
"description": "Whether the target receives the identity of the logged-in user as request headers.",
"type": "boolean"
},
"path": {
"example": "/admin",
"type": "string"
},
"rules": {
"additionalProperties": false,
"description": "Who may pass after logging in. A user needs to match one of the rules; at least one rule is set.",
"properties": {
"allowAnyAuthenticatedUser": {
"description": "Every user the provider authenticates may pass. Only with the OIDC provider.",
"type": "boolean"
},
"allowedEmailDomains": {
"items": {
"example": "example.com",
"format": "idn-hostname",
"type": "string"
},
"type": "array"
},
"allowedEmails": {
"items": {
"example": "ada@example.com",
"format": "email",
"type": "string"
},
"type": "array"
},
"projectMembersOnly": {
"description": "Only members of the Ingress's Project may pass. Requires the mStudio provider.",
"type": "boolean"
}
},
"required": [
"projectMembersOnly",
"allowedEmails",
"allowedEmailDomains",
"allowAnyAuthenticatedUser"
],
"type": "object"
}
},
"required": [
"path",
"rules",
"passIdentityHeaders"
],
"type": "object"
},
"type": "array"
},
"provider": {
"oneOf": [
{
"additionalProperties": false,
"description": "Users log in with their mStudio account.",
"properties": {
"mstudio": {
"additionalProperties": false,
"type": "object"
}
},
"required": [
"mstudio"
],
"type": "object"
},
{
"additionalProperties": false,
"description": "Users log in with an external OpenID Connect provider. The client secret is never returned.",
"properties": {
"oidc": {
"additionalProperties": false,
"properties": {
"clientId": {
"type": "string"
},
"issuerUrl": {
"example": "https://idp.example.com",
"format": "uri",
"type": "string"
}
},
"required": [
"issuerUrl",
"clientId"
],
"type": "object"
}
},
"required": [
"oidc"
],
"type": "object"
}
]
}
},
"required": [
"provider",
"paths"
],
"type": "object"
},
"dnsValidationErrors": {
"description": "A list of errors that occurred while validating the ingress's dns before requesting a certificate. `ERROR_QUAD_A` and `ERROR_NO_A_RECORD` are deprecated and no longer reported.",
"items": {
"enum": [
"ERROR_UNSPECIFIED",
"ERROR_QUAD_A",
"ERROR_NO_A_RECORD",
"ERROR_ACME_CERTIFICATE_REQUEST_DEADLINE_EXCEEDED"
],
"type": "string"
},
"type": "array"
},
"hostname": {
"format": "idn-hostname",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"ips": {
"properties": {
"v4": {
"items": {
"format": "ipv4",
"type": "string"
},
"type": "array"
},
"v6": {
"items": {
"format": "ipv6",
"type": "string"
},
"type": "array"
}
},
"required": [
"v4",
"v6"
],
"type": "object"
},
"isDefault": {
"description": "Whether this ingress is the default ingress or not. A default ingress is automatically created, it cannot be deleted. There can be only one default ingress per project.",
"type": "boolean"
},
"isDomain": {
"type": "boolean"
},
"isEnabled": {
"type": "boolean"
},
"ownership": {
"properties": {
"txtRecord": {
"type": "string"
},
"verified": {
"description": "Whether the domain ownership is verified or not.",
"type": "boolean"
}
},
"required": [
"verified"
],
"type": "object"
},
"paths": {
"description": "A list of paths. The default path `/` is always present and cannot be removed.",
"items": {
"properties": {
"path": {
"type": "string"
},
"target": {
"oneOf": [
{
"properties": {
"url": {
"format": "uri",
"type": "string",
"description": "The URL to which requests should be forwarded.",
"example": "https://redirect-target.example"
}
},
"required": [
"url"
],
"type": "object",
"description": "Redirect requests to this path to another URL"
},
{
"properties": {
"installationId": {
"format": "uuid",
"type": "string",
"description": "The ID of an app installation within the same project to which requests should be forwarded."
}
},
"required": [
"installationId"
],
"type": "object",
"description": "Serve a specific app installation"
},
{
"properties": {
"useDefaultPage": {
"type": "boolean",
"description": "Set this to `true` to serve a generic default site at this path."
}
},
"required": [
"useDefaultPage"
],
"type": "object",
"description": "Serve a generic default page"
},
{
"properties": {
"container": {
"properties": {
"id": {
"format": "uuid",
"type": "string"
},
"portProtocol": {
"description": "docker-compose port specification in format port/protocol (e.g. 8080/TCP)",
"format": "docker-network-port",
"type": "string",
"example": "80/tcp"
}
},
"required": [
"id",
"portProtocol"
],
"type": "object",
"descriptions": "References a specific port/container combination within the same project."
}
},
"required": [
"container"
],
"type": "object",
"description": "Forward requests to this path to a specific container."
}
]
}
},
"required": [
"path",
"target"
],
"type": "object"
},
"type": "array"
},
"projectId": {
"format": "uuid",
"type": "string"
},
"senderLoginProtection": {
"description": "If enabled, only mailboxes of the Ingress's Project may send emails from addresses of the Ingress and its SubIngresses. Only set on the root Ingress, as it covers all of its SubIngresses.",
"type": "boolean"
},
"tls": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"acme": {
"description": "Has to be `true`, as ssl cannot be deactivated.",
"type": "boolean"
},
"isCreated": {
"type": "boolean"
},
"requestDeadline": {
"format": "date-time",
"type": "string"
}
},
"required": [
"acme",
"isCreated"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"certificateId": {
"format": "uuid",
"type": "string"
}
},
"required": [
"certificateId"
],
"type": "object"
}
]
}
},
"required": [
"id",
"hostname",
"projectId",
"isDefault",
"tls",
"paths",
"isEnabled",
"ips",
"dnsValidationErrors",
"ownership"
],
"type": "object"
},
"type": "array"
}
Format
application/json
Description
The requested resource was not found
- messagestringrequired
- typestringrequired
Content-Type: application/json
{
"message": "Something went wrong",
"type": "InternalServerError"
}
{
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"message": {
"type": "string",
"example": "Something went wrong"
},
"type": {
"type": "string",
"example": "InternalServerError"
}
}
}
Format
application/json
Description
Your request ran into a rate limit. You have to wait until rate limit expires
- messagestring
- typestring
Content-Type: application/json
{
"message": "too many requests",
"type": "RateLimitError"
}
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "too many requests"
},
"type": {
"type": "string",
"example": "RateLimitError"
}
}
}
Format
application/json
Description
An unexpected Error that occurred while handling the request
- messagestringrequired
- typestringrequired
Content-Type: application/json
{
"message": "Something went wrong",
"type": "InternalServerError"
}
{
"type": "object",
"required": [
"type",
"message"
],
"properties": {
"message": {
"type": "string",
"example": "Something went wrong"
},
"type": {
"type": "string",
"example": "InternalServerError"
}
}
}
Usage examples
$ curl \
--fail \
--location \
-H "Authorization: Bearer $MITTWALD_API_TOKEN" \
https://api.mittwald.de/v2/ingresses?projectId=string&certificateId=f0f86186-0a5a-45b2-aa33-502777496347&hostnameSubstring=string&appInstallationId=string&containerId=f0f86186-0a5a-45b2-aa33-502777496347&limit=50&page=1
import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { assertStatus } from "@mittwald/api-client-commons";
const client = MittwaldAPIClient.newWithToken(process.env.MITTWALD_API_TOKEN);
const response = await client.domain.ingressListIngresses({
"queryParameters": {
"projectId": "string",
"certificateId": "f0f86186-0a5a-45b2-aa33-502777496347",
"hostnameSubstring": "string",
"appInstallationId": "string",
"containerId": "f0f86186-0a5a-45b2-aa33-502777496347",
"limit": 50,
"page": 1
}
});
assertStatus(response, 200);
use \Mittwald\ApiClient\Generated\V2\Clients\Domain\IngressListIngresses\IngressListIngressesRequest;
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));
$request = (new IngressListIngressesRequest())
->withProjectId("string")
->withCertificateId("f0f86186-0a5a-45b2-aa33-502777496347")
->withHostnameSubstring("string")
->withAppInstallationId("string")
->withContainerId("f0f86186-0a5a-45b2-aa33-502777496347")
->withLimit(50)
->withPage(1);
$response = $client->domain()->ingressListIngresses($request);
var_dump($response->getBody();