Get an organization's email relay (admin)
Docs version v1 (main)Nauthera is pre-1.0, in a design-partner program
/v1/admin/orgs/{slug}/mailReturns the SMTP relay the organization's email is sent through, read-only:
its own (configured in the deployment, Helm mailOrganizations), the
deployment's when it has none, or none. Reports whether credentials are
configured but never reads or returns them. Requires the
nauthera.orgs:read scope and the orgs.read permission, admitted as
reading the organization is.
The organization slug. It names the TENANT OF RECORD for the operation: the rows it reads and writes, the policy its secrets are derived under, and the organization its audit record is filed against all come from this organization. A token is admitted only through its own slug, except a main-org token, which may be admitted through any — so cross-tenant administration is performed through the TARGET tenant's slug, never by naming its resources through another. A token reaching for a slug it may not be admitted through is refused identically whether that organization exists or not.
1–64 characters
- DPoPstring
DPoP proof JWT (RFC 9449 §4). REQUIRED on a request presenting a DPoP-bound access token, and it must be signed by the key named in the token's
cnf.jktand cover this request's method and URI. The proof is read from the request itself rather than from this decoded parameter, so every protected operation is covered whether or not it declares it.
200 OKapplication/jsonThe organization's email relay.
The organization's email relay.
Headers
Cache-Controlno-store
Body
The SMTP relay an organization's email is sent through, for display. It is configured in the deployment (Helm
mailOrganizations, or the deployment-wideconfig.mail), not through the API. Credentials are never read or returned, only whether they are configured.organization: the organization's own relay.deployment: the deployment's, the organization having none.none: neither, so the organization cannot send email.Possible values3 valuesorganizationdeploymentnone
Whether the relay authenticates with a username and password.
- hoststring
The relay's host name or IP address.
at most 253 characters
- portinteger
between 1 and 65535
- tls_modeenum
How the connection is secured.
noneis a relay the operator explicitly configured without TLS: messages, and credentials if it authenticates, cross the network unencrypted.Possible values3 valuesstarttlsimplicitnone
- from_addressstring
The sender address messages carry.
at most 254 characters
- from_namestring
at most 256 characters
- reply_tostring
at most 254 characters
401 Unauthorizedapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
Cache-Controlno-storeWWW-AuthenticatestringDPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the last path segment oftype), so consumers can branch on it without parsing prose.typeishttps://nauthera.io/problems/<code>, which resolves to the code's runbook: why it happened, who is affected and what to do (RFC 9457 §3.1.1). A problem without a code hasabout:blank.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"https://nauthera.io/problems/validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values43 valuesinvalid_requestinvalid_credentialsforbiddenunauthorizedinsufficient_user_authenticationprotected_accountpassword_held_by_directorylast_role_administratorinvalid_codetoo_many_requeststoo_many_attemptsaccount_lockedaccount_unavailablealready_enrolledregistration_disabledregistration_conflictcaptcha_failedinvalid_reset_linkpassword_reusedpassword_too_shortpassword_too_longpassword_compromisedinvalid_verification_linkinvalid_invitation_linkmail_relay_missingemail_unverifiednot_foundconflictunavailablebusywindow_too_largetoo_many_seriesinternal_errorrate_limitedmalformedbody_too_largerequiredvalidation_errorunknown_orginvalid_tokeninvalid_dpop_proofuse_dpop_nonceserver_error
- instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"
403 Forbiddenapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
Cache-Controlno-storeWWW-AuthenticatestringDPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the last path segment oftype), so consumers can branch on it without parsing prose.typeishttps://nauthera.io/problems/<code>, which resolves to the code's runbook: why it happened, who is affected and what to do (RFC 9457 §3.1.1). A problem without a code hasabout:blank.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"https://nauthera.io/problems/validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values43 valuesinvalid_requestinvalid_credentialsforbiddenunauthorizedinsufficient_user_authenticationprotected_accountpassword_held_by_directorylast_role_administratorinvalid_codetoo_many_requeststoo_many_attemptsaccount_lockedaccount_unavailablealready_enrolledregistration_disabledregistration_conflictcaptcha_failedinvalid_reset_linkpassword_reusedpassword_too_shortpassword_too_longpassword_compromisedinvalid_verification_linkinvalid_invitation_linkmail_relay_missingemail_unverifiednot_foundconflictunavailablebusywindow_too_largetoo_many_seriesinternal_errorrate_limitedmalformedbody_too_largerequiredvalidation_errorunknown_orginvalid_tokeninvalid_dpop_proofuse_dpop_nonceserver_error
- instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"
404 Not Foundapplication/problem+jsonProblem details (RFC 9457).
Problem details (RFC 9457).
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the last path segment oftype), so consumers can branch on it without parsing prose.typeishttps://nauthera.io/problems/<code>, which resolves to the code's runbook: why it happened, who is affected and what to do (RFC 9457 §3.1.1). A problem without a code hasabout:blank.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"https://nauthera.io/problems/validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values43 valuesinvalid_requestinvalid_credentialsforbiddenunauthorizedinsufficient_user_authenticationprotected_accountpassword_held_by_directorylast_role_administratorinvalid_codetoo_many_requeststoo_many_attemptsaccount_lockedaccount_unavailablealready_enrolledregistration_disabledregistration_conflictcaptcha_failedinvalid_reset_linkpassword_reusedpassword_too_shortpassword_too_longpassword_compromisedinvalid_verification_linkinvalid_invitation_linkmail_relay_missingemail_unverifiednot_foundconflictunavailablebusywindow_too_largetoo_many_seriesinternal_errorrate_limitedmalformedbody_too_largerequiredvalidation_errorunknown_orginvalid_tokeninvalid_dpop_proofuse_dpop_nonceserver_error
- instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"
429 Too Many Requestsapplication/problem+jsonToo many requests.
Too many requests.
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the last path segment oftype), so consumers can branch on it without parsing prose.typeishttps://nauthera.io/problems/<code>, which resolves to the code's runbook: why it happened, who is affected and what to do (RFC 9457 §3.1.1). A problem without a code hasabout:blank.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"https://nauthera.io/problems/validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values43 valuesinvalid_requestinvalid_credentialsforbiddenunauthorizedinsufficient_user_authenticationprotected_accountpassword_held_by_directorylast_role_administratorinvalid_codetoo_many_requeststoo_many_attemptsaccount_lockedaccount_unavailablealready_enrolledregistration_disabledregistration_conflictcaptcha_failedinvalid_reset_linkpassword_reusedpassword_too_shortpassword_too_longpassword_compromisedinvalid_verification_linkinvalid_invitation_linkmail_relay_missingemail_unverifiednot_foundconflictunavailablebusywindow_too_largetoo_many_seriesinternal_errorrate_limitedmalformedbody_too_largerequiredvalidation_errorunknown_orginvalid_tokeninvalid_dpop_proofuse_dpop_nonceserver_error
- instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"
Errorapplication/problem+jsonProblem details (RFC 9457) with an RFC 6750 / RFC 9449 challenge.
Headers
Cache-Controlno-storeWWW-AuthenticatestringDPoP-Noncestring
Body
RFC 9457 (formerly RFC 7807) problem details (application/problem+json).
codeis a stable machine-readable slug for the problem kind (it mirrors the last path segment oftype), so consumers can branch on it without parsing prose.typeishttps://nauthera.io/problems/<code>, which resolves to the code's runbook: why it happened, who is affected and what to do (RFC 9457 §3.1.1). A problem without a code hasabout:blank.errorsis present on validation failures and lists every offending field.- Example
"Request validation failed" - Example
400 - typestring · uriExample
"https://nauthera.io/problems/validation_error" - detailstringExample
"One or more fields did not satisfy the API schema." - codeenum
The kind of problem, as a stable machine-readable slug a client branches on and translates rather than parsing
titleordetail, which are English prose for logs. A problem whose status says everything the server knows carries nocode.Show moreShow less
validation_erroris the one code whose message is not a sentence about the code itself: the request failed the schema, and the specifics are theerrorslist — one entry per offending field — which a form renders on those fields.requiredandmalformedare spelled like two of the per-field violation codes (FieldError.code) but mean something else; the two vocabularies are told apart by position, never by spelling.Compatibility: this is a CLOSED enum, with the same cost as
AuditAction: a client generated against an older version of this document rejects a problem carrying a code added after it was built. Regenerate on upgrade, or decode the field as a plain string. It is enumerated anyway so that what a client must translate is knowable from the contract alone.Possible values43 valuesinvalid_requestinvalid_credentialsforbiddenunauthorizedinsufficient_user_authenticationprotected_accountpassword_held_by_directorylast_role_administratorinvalid_codetoo_many_requeststoo_many_attemptsaccount_lockedaccount_unavailablealready_enrolledregistration_disabledregistration_conflictcaptcha_failedinvalid_reset_linkpassword_reusedpassword_too_shortpassword_too_longpassword_compromisedinvalid_verification_linkinvalid_invitation_linkmail_relay_missingemail_unverifiednot_foundconflictunavailablebusywindow_too_largetoo_many_seriesinternal_errorrate_limitedmalformedbody_too_largerequiredvalidation_errorunknown_orginvalid_tokeninvalid_dpop_proofuse_dpop_nonceserver_error
- instancestringExample
"/introspect" - request_idstringExample
"8d94ed49-1caf-4ab3-9594-557142f2d023" - trace_idstring
Distributed-trace id (hex) for correlating this response with traces and logs. Present only when tracing is enabled and the request was recorded. Opaque and safe to log/share.
Example"4bf92f3577b34da6a3ce929d0e0e4736" - errorsarray of objects
Field-level violations (present for validation errors).
Each item:A single field-level validation violation.
Show item attributesHide item attributes
Offending field, dotted for nested bodies (e.g. child.id).
Example"token_type_hint"Machine-readable violation code: required, too_short, too_long, pattern, invalid_format, not_allowed, minimum, maximum, multiple_of, too_few, too_many, not_unique, malformed.
Example"not_allowed"- Example
"field token_type_hint must be one of [access_token, refresh_token]"