Download OpenAPI specification:
The specification describes the onway registrar API. Most responses of the API are structured according to the same schema.
| Field Name | Type | Description |
|---|---|---|
| status | integer | The HTTP status code of the response. |
| content | varies by endpoint | Contains the endpoint specific content of the response if the request was successful. |
| links | object | Contains useful URI templates (RFC 6570) to other endpoints within the context of the response. The response schemes in this specification do not contain any links to keep it clear and concise. |
| problem | object | Contains information about the error if the request was not successful. |
| Field Name | Type | Description |
|---|---|---|
| type | string | The type of the problem. |
| title | string | A human-readable title. |
| message | string | Contains the error message itself. |
| violations | array | Provides information about errors on specific fields. |
| Field Name | Type | Description |
|---|---|---|
| field | string | Name of the field. |
| message | string | The error message. |
The API uses only the following status codes:
The 200 (OK) status code indicates that the request has succeeded.
The payload sent in a 200 response depends on the request method.
The 400 (Bad Request) status code indicates that the server cannot or
will not process the request due to something that is perceived to be a
client error (e.g., malformed request syntax, invalid request message
framing, or deceptive request routing).
The 401 (Unauthorized) status code indicates that the request has not
been applied because it lacks valid authentication credentials for the
target resource.
The 403 (Forbidden) status code indicates that the server understood
the request but refuses to authorize it.
The 404 (Not Found) status code indicates that the origin server
did not find a current representation for the target resource or is not
willing to disclose that one exists. A 404 status code does not indicate
whether this lack of representation is temporary or permanent.
The 429 (Too Many Requests) status code indicates that the client
has sent too many requests in a given amount of time. This mechanism of
asking the client to slow down the rate of requests is commonly called
"rate limiting".
The 500 (Internal Server Error) status code indicates that the server
encountered an unexpected condition that prevented it from fulfilling the
request.
Some endpoints require the user to be logged in. For browser-based clients a cookie will be set on successful authentication and no further action is required. For non-browser clients a bearer token must be sent in the Authorization header with each request. The token can be obtained via the authentication API.
Browser-based clients using cookie authentication must include a CSRF token in a header named X-XSRF-TOKEN with
each request to a secured endpoint. The required CSRF token is found in the cookie XSRF-TOKEN, which is sent from
the server with every API response. This requirement does not apply if the authentication token is sent in the
Authorization header of the request.
The onway registrar uses Friendly Captcha V2 to prevent automated registration of phone numbers. The service can be enabled/disabled in the backend. It is enabled by default.
The onway registrar supports two different ways to register for OpenRoaming:
You will receive an authentication token after successful authentication. This token is used for further API calls. For browser-based clients this is handled automatically via the cookie that is set on login. SMS authentication is protected by a captcha by default.
Create a verification code and send it to a phone number. The verification code is valid for a limited amount of time, e.g. 90 seconds and must be verified within that time.
Rate limiting is applied to this endpoint.
Note: The following conditions are only valid if Friendly Captcha is enabled.
| phoneNumber required | string SMS capable phone number. |
| frcCaptchaResponse | string When the captcha challenge is completed by the user, the user's web browser receives a piece of text that proves that they completed the challenge. This proof is called the response. |
{- "phoneNumber": "+41791234567",
- "frcCaptchaResponse": "1234567890ABCDEF..."
}{- "status": 200,
- "reason": "OK",
- "content": { }
}Verify the verification code and register your phone number on onway registrar. A rate limitation prevents too many verification attempts for the same phone number, e.g. 5 tries within 90 seconds.
| phoneNumber required | string Phone number that has received the verification code. |
| verificationCode required | string Verification code to register. |
{- "phoneNumber": "+41791234567",
- "verificationCode": "1234"
}{- "status": 200,
- "reason": "OK",
- "content": {
- "token": "dfa11c84-56a4-440d-bd54-b085cf71d7b3"
}
}This endpoint executes steps 6-8 of the Authorization Code Flow Steps as well as the UserInfo Request and should not be called by a JavaScript client, but directly by the browser of the End-User.
If the End-User authentication was successful the server uses the Authorization Code from the Successful Authentication Response to send a Token Request to the OpenID Provider.
The server then uses the Access Token to send a UserInfo Request.
If all requests where successful and the UserInfo Response contains a phone number, the End-User is redirected to the success path. If the End-User authentication was not successful, the Token Request or UserInfo Request failed or if the UserInfo Response does not contain a phone number, the End-User is redirected to the error path. The "Responses" section contains more details about the redirect.
{- "status": 500,
- "reason": "Internal Server Error",
- "problem": {
- "type": "string",
- "title": "string",
- "message": "string",
- "violations": [
- {
- "field": "string",
- "message": "string"
}
]
}
}Logout from your onway registrar session. The session is terminated automatically after some idle time, e.g. 15 minutes.
curl -H "Authorization: Bearer <your_auth_token>" -X POST https://registrar.example.com/api/logout
{- "status": 200,
- "reason": "OK"
}Methods for user-related actions. These include actions such as downloading OpenRoaming profiles or deleting associated user accounts.
Endpoint to download an OpenRoaming profile. This endpoint is intended to be called from an Android device. After a successful download, the profile must be installed on the device.
There are two scenarios in which this endpoint responds with a redirect (302 Found):
curl -H "Authorization: Bearer <your_auth_token>" -O https://registrar.example.com/api/download-profile/android
Endpoint to download an OpenRoaming profile. This endpoint is intended to be called from an Apple device, such as iPhone, iPad, Macbook, etc. After a successful download, the profile must be installed on the device.
There are two scenarios in which this endpoint responds with a redirect (302 Found):
curl -H "Authorization: Bearer <your_auth_token>" -o open-roaming-profile-apple.mobileconfig https://registrar.example.com/api/download-profile/apple
Endpoint to initiate a download of an OpenRoaming profile. This endpoint is intended to be called from a Windows device. It does not return the profile directly, but responds with a redirect (303 See Others) to a location that opens the Windows Settings application to download the profile. For security reasons, the download location is only valid for a certain period of time. Once this period has expired, a new download redirect URL must be requested via this endpoint. After a successful download, the profile must be installed on the device.
There are two scenarios in which this endpoint responds with a redirect (302 Found):
curl -H "Authorization: Bearer <your_auth_token>" -o open-roaming-profile-windows.xml https://registrar.example.com/api/download-profile/windows
Get the OpenRoaming account with the account data such as the registered phone number.
curl -H "Authorization: Bearer <your_auth_token>" https://registrar.example.com/api/account
{- "status": 200,
- "reason": "OK",
- "content": {
- "phoneNumber": "+41791234567"
}
}Delete the OpenRoaming account and invalidate any authenticated sessions that use the same registered phone number.
curl -H "Authorization: Bearer <your_auth_token>" -X DELETE https://registrar.example.com/api/account
{- "status": 200,
- "reason": "OK",
- "content": 1
}Get the SMS metadata. It contains information that is required by the Friendly Captcha browser widget.
curl https://registrar.example.com/api/sms/metadata
{- "status": 200,
- "reason": "OK",
- "content": {
- "frcCaptcha": {
- "enabled": true,
- "sitekey": "FC1234567890ABCD"
}
}
}Check if your session is authenticated.
curl -H "Authorization: Bearer <your_auth_token>" https://registrar.example.com/api/is-authenticated
{- "status": 200,
- "reason": "OK",
- "content": true
}curl -H "Authorization: Bearer <your_auth_token>" https://registrar.example.com/api/version
{- "status": 200,
- "reason": "OK",
- "content": {
- "version": "1.0.0",
- "buildDate": "2025-02-17T12:35:18Z",
- "idAbbreviation": "98a5648"
}
}