Skip to content

domain_allows.md

Latest commit

 

History

History
272 lines (194 loc) · 5.75 KB

domain_allows.md

File metadata and controls

272 lines (194 loc) · 5.75 KB
Raw
title admin/domain_allows API methods
description Allow certain domains to federate.
menu
docs
name parent identifier
domain_allows
methods-admin
methods-admin-domain_allows
aliases
/methods/admin/domain_allows
/api/methods/admin/domain_allows
<style> #TableOfContents ul ul ul {display: none} </style>

This endpoint creates rules to allow only the specified domains to federate with your server. This only applies when LIMITED_FEDERATION_MODE is enabled. This is the inverse of the Domain Blocks functionality, and cannot be used to override a wild-card domain block.

List all allowed domains {#get}

GET /api/v1/admin/domain_allows HTTP/1.1

Show information about all allowed domains.

Returns: Array of [Admin::DomainAllow]({{< relref "entities/Admin_DomainAllow" >}})
OAuth: User token + admin:read:domain_allows
Permissions: Manage Federation
Version history:
4.0.0 - added

Request

Headers

Authorization : {{}} Provide this header with Bearer <user_token> to gain authorized access to this API method.

Query parameters

max_id : Internal parameter. Use HTTP Link header for pagination.

since_id : Internal parameter. Use HTTP Link header for pagination.

min_id : Internal parameter. Use HTTP Link header for pagination.

limit : Integer. Maximum number of results to return. Defaults to 100 allows. Max 200 allows.

Response

200: OK
[
	{
		"id": "2",
		"domain": "mastodon",
		"created_at": "2022-09-14T21:24:15.360Z"
	},
	{
		"id": "1",
		"domain": "mastodon.social",
		"created_at": "2022-09-14T21:23:02.755Z"
	}
]

Because DomainAllow IDs are generally not exposed via any API responses, you will have to parse the HTTP Link header to load older or newer results. See [Paginating through API responses]({{<relref "api/guidelines#pagination">}}) for more information.

Link: <http://mastodon.example/api/v1/admin/domain_allows?limit=2&max_id=2>; rel="next", <http://mastodon.example/api/v1/admin/domain_allows?limit=2&since_id=1>; rel="prev"
403: Forbidden

Authorized user is not allowed to perform this action, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}

Get a single allowed domain {#get-one}

GET /api/v1/admin/domain_allows/:id HTTP/1.1

Show information about a single allowed domain.

Returns: [Admin::DomainAllow]({{< relref "entities/Admin_DomainAllow" >}})
OAuth: User token + admin:read:domain_allows
Permissions: Manage Federation
Version history:
4.0.0 - added

Path parameters

:id : {{}} String. The ID of the DomainAllow in the database.

Headers

Authorization : {{}} Provide this header with Bearer <user_token> to gain authorized access to this API method.

Response

200: OK
{
	"id": "1",
	"domain": "mastodon.social",
	"created_at": "2022-09-14T21:23:02.755Z"
}
403: Forbidden

Authorized user is not allowed to perform this action, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}
404: Not found

DomainAllow with the given ID does not exist

{
	"error": "Record not found"
}

Allow a domain to federate {#create}

POST /api/v1/admin/domain_allows HTTP/1.1

Add a domain to the list of domains allowed to federate, to be used when the instance is in allow-list federation mode.

Returns: [Admin::DomainAllow]({{< relref "entities/Admin_DomainAllow" >}})
OAuth: User token + admin:write:domain_allows
Permissions: Manage Federation
Version history:
4.0.0 - added

Request

Headers

Authorization : {{}} Provide this header with Bearer <user_token> to gain authorized access to this API method.

Form data parameters

domain : {{}} String. The domain to allow federation with.

Response

200: OK

Domain has been allowed to federate, or was already allowed to federate

{
	"id": "1",
	"domain": "mastodon.social",
	"created_at": "2022-09-14T21:23:02.755Z"
}
403: Forbidden

Authorized user is not allowed to perform this action, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}
422: Unprocessable entity

The domain parameter was not provided or was invalid

{
	"error": "Validation failed: Domain can't be blank"
}

Delete an allowed domain {#delete}

DELETE /api/v1/admin/domain_allows/:id HTTP/1.1

Delete a domain from the allowed domains list.

Returns: [Admin::DomainAllow]({{< relref "entities/Admin_DomainAllow" >}})
OAuth: User token + admin:write:domain_allows
Permissions: Manage Federation
Version history:
4.0.0 - added

Request

Path parameters

:id : {{}} String. The ID of the DomainAllow in the database.

Headers

Authorization : {{}} Provide this header with Bearer <user_token> to gain authorized access to this API method.

Response

200: OK

The allowed domain has been removed from the allow list

{
	"id": "4",
	"domain": "*",
	"created_at": "2022-09-14T21:32:44.945Z"
}
403: Forbidden

Authorized user is not allowed to perform this action, or invalid or missing Authorization header

{
  "error": "This action is not allowed"
}
404: Not found

DomainAllow with the given ID does not exist

{
	"error": "Record not found"
}

See also

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/admin/domain_allows_controller.rb" caption="app/controllers/api/v1/admin/domain_allows_controller.rb" >}}