Prerequisites

• Issued client_id and client_secret (request via onboarding and access), and your organizationBusinessId.
• Network egress to the selected environment and token endpoint (provided during onboarding).
• Tooling: curl or Postman, and a JSON editor/validator.

Environments

External users: STG and PRD only. DEV/TST are internal to the MNSW team.

The exact issuer and token URL are shared during onboarding. Replace <TOKEN_URL> in examples accordingly.

Architecture at a glance

1. 1Your system

   Requests a token with OAuth2 client credentials.

2. 2Keycloak

   Returns an access token (JWT).

3. 3National API

   Accepts authorized port-call and formality requests.

4. 4MIG schema

   Validate the formality payload before sending it.

Step-by-step

1) Get an access token

Use the client issued for your organization (declarant or port) with the OAuth2 Client Credentials grant. The flow is identical for both.

• STG: https://mnsw-stg.mnsw.fi/keycloak/realms/nemo/protocol/openid-connect/token
• PRD: https://mnsw.mnsw.fi/keycloak/realms/nemo/protocol/openid-connect/token

Only STG and PRD are supported for external integrators. DEV/TST are for the MNSW team only.

ENV=stg   # or prd
case "$ENV" in
  stg) IDP_HOST=mnsw-stg.mnsw.fi/keycloak ;;
  prd) IDP_HOST=mnsw.mnsw.fi/keycloak ;;
  *) echo "Use stg or prd (DEV/TST are internal)"; exit 1 ;;
esac

TOKEN_URL="https://$IDP_HOST/realms/nemo/protocol/openid-connect/token"
CLIENT_ID=<client_id>
CLIENT_SECRET=<secret>

ACCESS_TOKEN=$(curl --fail-with-body -sS -X POST "$TOKEN_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" | jq -er '.access_token // empty')

Keep client secrets and access tokens out of source control, logs, and shared messages. Send the access token using the standard OAuth2 authorization scheme, together with the organizationBusinessId header.

2) Smoke test your token

Call an authorized endpoint to verify the token and organization header:

export BASE=https://mnsw-stg.mnsw.fi
export ACCESS_TOKEN=<access_token>
export ORG_BID=<your_organizationBusinessId>

curl -i "$BASE/nemo-ui/api/v1/codelists/names" \
  --oauth2-bearer "$ACCESS_TOKEN" \
  -H "organizationBusinessId: $ORG_BID"

3) Build a minimal formality payload

Start from the EMSA MIG JSON Schema for the formality type (for example NOA, NOD, or CGD), populate required fields, and follow national rules where applicable.

4) Submit the formality

Submit to the Declarant API endpoint for the port call. The API accepts formalityData as an application/json multipart field. Use the formality ID when updating an existing formality.

export VISIT_ID=<portcall-visitId>
export FORM_TYPE=NOA  # e.g., NOA, NOD, CGA, CGD, ATA, ATD
export FORM_ID=<stable-formality-uuid>

curl -i -X POST "$BASE/declarant-api/v1/portcalls/$VISIT_ID/formalities/$FORM_TYPE" \
  --oauth2-bearer "$ACCESS_TOKEN" \
  -H "organizationBusinessId: $ORG_BID" \
  -F "formalityData=@payload.json;type=application/json"

# Update the same formality later:
curl -i -X PUT "$BASE/declarant-api/v1/portcalls/$VISIT_ID/formalities/$FORM_TYPE/$FORM_ID" \
  --oauth2-bearer "$ACCESS_TOKEN" \
  -H "organizationBusinessId: $ORG_BID" \
  -F "formalityData=@payload.json;type=application/json"

5) Validate and troubleshoot

• Validate JSON against the MIG 2.0.1.0 schema for the formality type.
• For 4xx errors, check the response body for EMSA MIG or national-rule validation errors.
• Include the request-id (if returned in headers or body) when contacting support.

FAQ

Docs & References

• National Declarant API reference
• EMSA — EMSWe Message Implementation Guide (MIG)
• Regulation (EU) 2019/1239 — EMSWe
• Domibus Technical Documentation
• OAuth 2.0 (RFC 6749)

Need help? Email nemo.support@emsw.fi.