Authentication

phoss SMP has two authentication surfaces:

Management UI — session-based login at /secure/.
REST API — HTTP request-level authentication on all write endpoints (PUT, DELETE).

REST API authentication

All write operations on the REST API require credentials. Two schemes are supported:

Bearer token (recommended)
Basic Auth (legacy)

Available since v6.0.7. Pass a token in the Authorization header:

Authorization: Bearer <token>

Example with curl:

curl -X PUT https://smp.example.org/iso6523-actorid-upis%3A%3A0088%3A123456789 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/xml" \
  --data-binary @service-group.xml

Tokens are created and managed in Administration > Security > User Tokens in the management UI. Each token is associated with a user account. Revoke a token at any time from the same page.

Use Bearer tokens for all new integrations. Unlike Basic Auth, a token can be revoked independently of the user password and never exposes the account credentials.

HTTP Basic Authentication is the legacy scheme. Encode email:password in Base64 and pass it in the Authorization header:

Authorization: Basic Base64(email:password)

Example with curl:

curl -X PUT https://smp.example.org/iso6523-actorid-upis%3A%3A0088%3A123456789 \
  -u [email protected]:password \
  -H "Content-Type: application/xml" \
  --data-binary @service-group.xml

Basic Auth transmits the account password on every request. Always use HTTPS when using Basic Auth, and prefer Bearer tokens for new integrations.

Which endpoints require authentication?

Method	Path	Auth required
GET	`/{ServiceGroupId}`	No
PUT	`/{ServiceGroupId}`	Yes
DELETE	`/{ServiceGroupId}`	Yes
GET	`/{ServiceGroupId}/services/{DocumentTypeId}`	No
PUT	`/{ServiceGroupId}/services/{DocumentTypeId}`	Yes
DELETE	`/{ServiceGroupId}/services/{DocumentTypeId}`	Yes
GET	`/businesscard/{ServiceGroupId}`	No
PUT	`/businesscard/{ServiceGroupId}`	Yes
DELETE	`/businesscard/{ServiceGroupId}`	Yes

The management UI at /secure/ uses server-side session authentication managed by the ph-oton framework. Sessions are maintained via a browser cookie.

Default credentials

Field	Default value
Email	`[email protected]`
Password	`password`

Change the default password on first login before exposing the server to a network. Navigate to Administration > Change Password after logging in.

By default the login page may indicate whether the email or the password was wrong. Disable this in production to avoid user enumeration:

webapp.security.login.errordetails = false

Creating and managing user tokens

Open /secure/ and sign in with an admin account.

Navigate to User Tokens

Go to Administration > Security > User Tokens.

Create a new token

Click Create new User Token. Assign it to a user account and optionally set an expiry date. Copy the generated token value — it is shown only once.

Use the token in API calls

Include Authorization: Bearer <token> in every write request.

Revoke a token when no longer needed

Return to User Tokens and delete the token. The corresponding Authorization: Bearer header will immediately start returning HTTP 401.

Security recommendations

Prefer Bearer tokens over Basic Auth for all API clients.
Use HTTPS in production. Basic Auth over plain HTTP sends credentials in clear text.
Disable login error details in production (webapp.security.login.errordetails = false).
Change the default admin password immediately after installation.
Rotate tokens regularly and revoke any that are no longer in use.
Avoid exposing /secure/ to the public internet where possible; restrict with a firewall or reverse-proxy ACL.

HTTP vs HTTPS

The SMP specification requires that the public SMP URL be reachable over HTTP (for some older clients) and/or HTTPS. For the management UI and write API, HTTPS is strongly recommended. Configure the public URL via:

smp.publicurl = https://smp.example.org

If phoss SMP is running behind a reverse proxy that terminates TLS, set:

smp.forceroot = true
smp.publicurl.mode = x-forwarded-header   # or: forwarded-header

Get Started

Installation

Configuration

Backends

Operations

Guides

REST API authentication

Which endpoints require authentication?

Default credentials

Creating and managing user tokens

Security recommendations

HTTP vs HTTPS

Build docs developers (and LLMs) love

Get Started

Installation

Configuration

Backends

Operations

Guides

​REST API authentication

​Which endpoints require authentication?

​Management UI login

​Default credentials

​Login error details

​Creating and managing user tokens

​Security recommendations

​HTTP vs HTTPS

Build docs developers (and LLMs) love

REST API authentication

Which endpoints require authentication?

Management UI login

Default credentials

Login error details

Creating and managing user tokens

Security recommendations

HTTP vs HTTPS