Skip to content

Script Development / API Authentication

For HTTP APIs generated by the Func API, you can add API authentication.

The following API authentication methods are currently supported:

Auth Type Description
Fixed Field Verifies that the Header, Query, or Body of the request contains a field with a specific value
HTTP Basic Standard HTTP Basic authentication (a login dialog pops up when accessed in a browser)
HTTP Digest Standard HTTP Digest authentication (a login dialog pops up when accessed in a browser)
Authentication Function Specify a self-written function as the authentication function

Users can add authentication configurations under "Admin / API Authentication", and then specify the added authentication configuration in "Func API Configuration".

If you have high security requirements, be sure to use HTTPS to access the API

1. Fixed Field Authentication

Fixed field authentication is the simplest authentication method. The client and DataFlux Func agree to include a specific field and field value at a certain location in the request (Header, Query, or Body), and attach this content on every call to complete authentication.

For example, if it is agreed that the request header must contain x-auth-token="my-auth-token" on every request, you can call it in the following way to complete authentication:

Text Only
1
2
GET /api/v1/al/func-api-xxxxx
x-auth-token: my-auth-token

When multiple fixed field authentication configurations are set, a match on any one of them is considered authentication passed

For fields used for authentication in Query and Body, the system will automatically remove them after authentication succeeds; they will not be passed to the function

2. HTTP Basic / HTTP Digest

An authentication method directly supported by browsers.

For APIs authenticated in this way, when you access the API directly in the browser address bar, the browser will pop up a username/password dialog for the user to fill in.

If you need to access it programmatically, refer to the following code:

Python
1
2
3
4
5
6
7
8
import requests
from requests.auth import HTTPBasicAuth, HTTPDigestAuth

# HTTP Basic authentication
resp = requests.get(url_1, auth=HTTPBasicAuth('user', 'password'))

# HTTP Digest authentication
resp = requests.get(url_2, auth=HTTPDigestAuth('user', 'password'))

3. Authentication Function

If the API authentication method is complex or special (for example, it needs to integrate with a business system), you can choose to write a custom function for authentication.

The function used for authentication takes no parameters. Returning True indicates successful authentication; returning any other value or throwing an error indicates failure.

In the authentication function, you can use the built-in variable _DFF_HTTP_REQUEST to obtain request-related information: Script Development / Built-in Variables / _DFF_HTTP_REQUEST

Example
1
2
3
@DFF.API('Authentication Function')
def my_auth_func():
    return _DFF_HTTP_REQUEST['headers']['x-auth-token'] == 'my-auth-token'

Note that when authentication fails, the response format of the API will vary depending on the returned content:

Example
1
2
3
@DFF.API('Authentication Function')
def my_auth_func():
    return False

When authentication fails and False is returned directly, the API response body will not contain any specific error message:

API Response Body
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "ok"     : false,
  "error"  : 401.99,
  "reason" : "EAPIAuth",
  "message": "Func Auth failed",
  "detail" : false,
  "status" : 401,
  "reqDump": {
    "method": "GET",
    "url"   : "http://localdev:8089/api/v1/func-api/xxxxx/s"
  },
  "traceId"   : "TRACE-XXXXX",
  "clientTime": null,
  "reqTime"   : "2025-08-14T11:03:45.238Z",
  "respTime"  : "2025-08-14T11:03:45.406Z",
  "reqCost"   : 168
}
Example
1
2
3
@DFF.API('Authentication Function')
def my_auth_func():
    return 'Bad User!'

When authentication fails and a string is returned, this string is returned as the detail field:

API Response Body
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "ok"     : false,
  "error"  : 401.99,
  "reason" : "EAPIAuth",
  "message": "Func Auth failed",
  "detail" : "Bad User!",
  "status" : 401,
  "reqDump": {
    "method": "GET",
    "url"   : "http://localdev:8089/api/v1/func-api/xxxxx/s"
  },
  "traceId"   : "TRACE-XXXXX",
  "clientTime": null,
  "reqTime"   : "2025-08-14T11:03:45.238Z",
  "respTime"  : "2025-08-14T11:03:45.406Z",
  "reqCost"   : 168
}
Example
1
2
3
@DFF.API('Authentication Function')
def my_auth_func():
    return { 'error': 'Bad User!' }

When authentication fails and a JSON object is returned, this JSON is returned as the detail field:

API Response Body
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "ok"     : false,
  "error"  : 401.99,
  "reason" : "EAPIAuth",
  "message": "Func Auth failed",
  "detail": {
    "error": "Bad User!"
  },
  "status": 401,
  "reqDump": {
    "method": "GET",
    "url"   : "http://localdev:8089/api/v1/func-api/xxxxx/s"
  },
  "traceId"   : "TRACE-XXXXX",
  "clientTime": null,
  "reqTime"   : "2025-08-14T11:03:45.238Z",
  "respTime"  : "2025-08-14T11:03:45.406Z",
  "reqCost"   : 168
}
Example
1
2
3
@DFF.API('Authentication Function')
def my_auth_func():
    raise Exception('Bad User!')

When the authentication function throws an error, as the Func framework cannot determine whether this Exception belongs to business logic or is an error from the code itself, it returns a generic error message as the detail field:

API Response Body
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "ok": false,
  "error": 401.99,
  "reason": "EAPIAuth",
  "message": "Func Auth failed",
  "detail": {
    "name"               : "Func.Runner",
    "id"                 : "task-RWLH3EuCRfYl",
    "triggerTime"        : 1755170213.119,
    "startTime"          : 1755170213.122,
    "endTime"            : 1755170213.13,
    "status"             : "failure",
    "exceptionType"      : "UserScriptException",
    "exception"          : "In User Script: Exception('Bad User!')",
    "exceptionFrom"      : "userScript",
    "originExceptionType": "Exception",
    "originException"    : "Exception('Bad User!')"
  },
  "status": 401,
  "reqDump": {
    "method": "GET",
    "url"   : "http://localdev:8089/api/v1/func-api/xxxxx/s"
  },
  "traceId"   : "TRACE-XXXXX",
  "clientTime": null,
  "reqTime"   : "2025-08-14T11:03:45.238Z",
  "respTime"  : "2025-08-14T11:03:45.406Z",
  "reqCost"   : 168
}