API Credentials¶

4 endpoints. Authentication, errors, paging and rate limits are described once, in the API overview.

Action	Method	Description
`createoauthcredential`	POST	Create an API credential
`deleteoauthcredential`	POST	Delete an API credential
`listoauthcredentials`	GET	List the API credentials
`updateoauthcredential`	POST	Update an API credential

createoauthcredential¶

Create an API credential.

POST /api/v1/createoauthcredential

Permission: manage_staff

Parameters

Name	Type	Required	Description
`description`	string	no	Up to 255 characters.
`allowed_ips`	string	no	The addresses it may be used from: IPv4 or IPv6 addresses and CIDR ranges, separated by commas (or an array). Left out, it works from anywhere.

Response

Field	Description
`result`	`success`
`credentialid`	integer
`identifier`	string
`secret`	string: shown this once, only its hash is stored
`allowed_ips`	array

Errors

Status	When
422	An allowed_ips entry is not an address or a range.

Note

The new credential belongs to the staff member whose credential made the call, with that account's permissions.

Example

curl -X POST https://example.com/api/v1/createoauthcredential \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

deleteoauthcredential¶

Delete an API credential.

POST /api/v1/deleteoauthcredential

Permission: manage_staff

Parameters

Name	Type	Required	Description
`credentialid`	integer	yes	The credential.

Response

Field	Description
`result`	`success`

Errors

Status	When
404	No such credential.

Example

curl -X POST https://example.com/api/v1/deleteoauthcredential \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "credentialid=1"

listoauthcredentials¶

List the API credentials.

GET /api/v1/listoauthcredentials

Permission: manage_staff

Parameters

None.

Response

Field	Description
`result`	`success`
`credentials`	array of {id, identifier, description, allowed_ips, created_at} for every active credential. Secrets are never returned.

Example

curl -G https://example.com/api/v1/listoauthcredentials \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

updateoauthcredential¶

Update an API credential.

POST /api/v1/updateoauthcredential

Permission: manage_staff

Parameters

Name	Type	Required	Description
`credentialid`	integer	yes	The credential.
`description`	string	no	Description.
`active`	boolean	no	Switch it on or off.
`allowed_ips`	string	no	Replace the addresses it may be used from (see createoauthcredential). Send it empty to allow anywhere.

Response

Field	Description
`result`	`success`
`credentialid`	integer

Errors

Status	When
404	No such credential.
422	An allowed_ips entry is not an address or a range.

Example

curl -X POST https://example.com/api/v1/updateoauthcredential \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "credentialid=1"