Stream authentication

The stream authentication function is currently in beta. Contact sales@agora.io before using it.

Set a timestamp authentication key

Sets a timestamp authentication key for the specified domain name.

HTTP request

PATCH https://api.agora.io/v1/projects/{appid}/fls/domains/{domain}

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID retrieved from Agora Console.
`domain`	String	Required. The domain name.

Request body

The request body is in the JSON Object type and contains the following fields:

Parameter	Type	Description
`authKey`	String	Required. The timestamp authentication key. Maximum length is 128 characters.

HTTP response

If the returned HTTP status code is 200, the request is successful.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status code for possible reasons.

Example

Request line

PATCH https://api.agora.io/v1/projects/{your_appid}/fls/domains/{your_domain} HTTP/1.1

Request body

{
    "authKey": "{your auth key}"
}

Response line

HTTP/1.1 200 OK

Configure origin authentication

Configures the settings of origin authentication.

HTTP request

PATCH https://api.agora.io/v1/projects/{appid}/fls/settings/streamauth/webhook

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID retrieved from Agora Console.

Request body

The request body is in the JSON Object type and contains the following fields:

Field	Type	Description
`enabled`	Boolean	Required. Whether to enable origin authentication: `true`: Enable origin authentication. `false`: (Default) Disable origin authentication.
`url`	String	Optional. The address of the server that handles origin authentication requests.
`secret`	String	Optional. The origin authentication secret. The process of generating a signature using the origin authentication secret is the same as that of the Notification Center Service. For details, see Signature Verification.

HTTP response

If the returned HTTP status code is 200, the request is successful.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status code for possible reasons.

Example

Request line

PATCH https://api.agora.io/v1/projects/{your_appid}/fls/settings/streamauth/webhook HTTP/1.1

Request body

{
    "enabled": true,
    "url": "www.test.com/auth/callback",
    "secret": "{ncs_secret}"
}

Response line

HTTP/1.1 200 OK

Get origin authentication configuration

Gets the configuration of origin authentication.

HTTP request

GET https://api.agora.io/v1/projects/{appid}/fls/settings/streamauth/webhook

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID retrieved from Agora Console.

HTTP response

If the returned HTTP status code is 200, the request is successful. The response body contains the following fields:

Field	Type	Description
`enabled`	Bool	Required. Whether origin authentication is enabled : `true`: Origin authentication is enabled. `false`: Origin authentication is disabled.
`url`	String	Optional. The address of the server that handles origin authentication requests.
`secret`	String	Optional. The origin authentication secret. The process of generating a signature using the origin authentication secret is the same as that of the Notification Center Service. For details, see Signature Verification.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status code for possible reasons.

Example

Request line

GET https://api.agora.io/v1/projects/{your_appid}/fls/settings/streamauth/webhook HTTP/1.1

Request body

{
    "enabled": true,
    "url": "www.test.com/auth/callback",
    "secret": "{ncs_secret}"
}

Response line

HTTP/1.1 200 OK

Format of origin authentication requests

Agora uses the following parameters to send requests to your server handling origin authentication:

Parameter	Type	Required	Description
`host`	String	Yes	The stream-pushing or -playing domain name.
`entryPoint`	String	Yes	The name of the entry point.
`streamName`	String	Yes	The stream name.
`cdnIp`	String	No	The IP address of the CDN node.
`clientIp`	String	No	The IP address of the client.
`token`	String	No	Authentication information.
`requestId`	String	No	The request ID.

The HTTP status code you return must be one of the following:

200: Origin authentication succeeds.
401: Origin authentication fails.

HTTP status code

Status code	Description
200	The request succeeds.
400	The parameter is invalid, for example the `appid` or the `entry_point` is empty, or the `region` parameter value is invalid.
401	Unauthorized (the customer ID and the customer secret do not match).
404	The server cannot find the resource according to the request, which means the requested entry point does not exist or the requested URI path is invalid.
500	An internal error occurs in the server, so the server is not able to complete the request.
504	An internal error occurs in the server. The gateway or the proxy server did not receive a timely request from the remote server.