An API exposing details of the treaties laid before Parliament.

Data around written questions and answers, as well as written ministerial statements.

Validate and generate passwords using open source tools

The recommended REST API endpoints to be used when integrating with PatientView

This is the API documentation for Patrowl Engines usage.

For general questions and support of the API, contact: webservices@paylocity.com # Overview Paylocity Web Services API is an externally facing RESTful Internet protocol. The Paylocity API uses HTTP verbs and a RESTful endpoint structure. OAuth 2.0 is used as the API Authorization framework. Request and response payloads are formatted as JSON. Paylocity supports v1 and v2 versions of its API endpoints. v1, while supported, won't be enhanced with additional functionality. For direct link to v1 documentation, please click [here](https://docs.paylocity.com/weblink/guides/Paylocity_Web_Services_API/v1/Paylocity_Web_Services_API.htm). For additional resources regarding v1/v2 differences and conversion path, please contact webservices@paylocity.com. ##### Setup Paylocity will provide the secure client credentials and set up the scope (type of requests and allowed company numbers). You will receive the unique client id, secret, and Paylocity public key for the data encryption. The secret will expire in 365 days. * Paylocity will send you an e-mail 10 days prior to the expiration date for the current secret. If not renewed, the second e-mail notification will be sent 5 days prior to secret's expiration. Each email will contain the code necessary to renew the client secret. * You can obtain the new secret by calling API endpoint using your current not yet expired credentials and the code that was sent with the notification email. For details on API endpoint, please see Client Credentials section. * Both the current secret value and the new secret value will be recognized during the transition period. After the current secret expires, you must use the new secret. * If you were unable to renew the secret via API endpoint, you can still contact Service and they will email you new secret via secure email. When validating the request, Paylocity API will honor the defaults and required fields set up for the company default New Hire Template as defined in Web Pay. # Authorization Paylocity Web Services API uses OAuth2.0 Authentication with JSON Message Format. All requests of the Paylocity Web Services API require a bearer token which can be obtained by authenticating the client with the Paylocity Web Services API via OAuth 2.0. The client must request a bearer token from the authorization endpoint: auth-server for production: https://api.paylocity.com/IdentityServer/connect/token auth-server for testing: https://apisandbox.paylocity.com/IdentityServer/connect/token Paylocity reserves the right to impose rate limits on the number of calls made to our APIs. Changes to API features/functionality may be made at anytime with or without prior notice. ##### Authorization Header The request is expected to be in the form of a basic authentication request, with the "Authorization" header containing the client-id and client-secret. This means the standard base-64 encoded user:password, prefixed with "Basic" as the value for the Authorization header, where user is the client-id and password is the client-secret. ##### Content-Type Header The "Content-Type" header is required to be "application/x-www-form-urlencoded". ##### Additional Values The request must post the following form encoded values within the request body: grant_type = client_credentials scope = WebLinkAPI ##### Responses Success will return HTTP 200 OK with JSON content: { "access_token": "xxx", "expires_in": 3600, "token_type": "Bearer" } # Encryption Paylocity uses a combination of RSA and AES cryptography. As part of the setup, each client is issued a public RSA key. Paylocity recommends the encryption of the incoming requests as additional protection of the sensitive data. Clients can opt-out of the encryption during the initial setup process. Opt-out will allow Paylocity to process unencrypted requests. The Paylocity Public Key has the following properties: * 2048 bit key size * PKCS1 key format * PEM encoding ##### Properties * key (base 64 encoded): The AES symmetric key encrypted with the Paylocity Public Key. It is the key used to encrypt the content. Paylocity will decrypt the AES key using RSA decryption and use it to decrypt the content. * iv (base 64 encoded): The AES IV (Initialization Vector) used when encrypting the content. * content (base 64 encoded): The AES encrypted request. The key and iv provided in the secureContent request are used by Paylocity for decryption of the content. We suggest using the following for the AES: * CBC cipher mode * PKCS7 padding * 128 bit block size * 256 bit key size ##### Encryption Flow * Generate the unencrypted JSON payload to POST/PUT * Encrypt this JSON payload using your _own key and IV_ (NOT with the Paylocity public key) * RSA encrypt the _key_ you used in step 2 with the Paylocity Public Key, then, base64 encode the result * Base64 encode the IV used to encrypt the JSON payload in step 2 * Put together a "securecontent" JSON object: { 'secureContent' : { 'key' : -- RSA-encrypted & base64 encoded key from step 3, 'iv' : -- base64 encoded iv from step 4 'content' -- content encrypted with your own key from step 2, base64 encoded } } ##### Sample Example { "secureContent": { "key": "eS3aw6H/qzHMJ00gSi6gQ3xa08DPMazk8BFY96Pd99ODA==", "iv": "NLyXMGq9svw0XO5aI9BzWw==", "content": "gAEOiQltO1w+LzGUoIK8FiYbU42hug94EasSl7N+Q1w=" } } ##### Sample C# Code using Newtonsoft.Json; using System; using System.IO; using System.Security.Cryptography; using System.Text; public class SecuredContent { [JsonProperty("key")] public string Key { get; set; } [JsonProperty("iv")] public string Iv { get; set; } [JsonProperty("content")] public string Content { get; set; } } public class EndUserSecureRequestExample { public string CreateSecuredRequest(FileInfo paylocityPublicKey, string unsecuredJsonRequest) { string publicKeyXml = File.ReadAllText(paylocityPublicKey.FullName, Encoding.UTF8); SecuredContent secureContent = this.CreateSecuredContent(publicKeyXml, unsecuredJsonRequest); string secureRequest = JsonConvert.SerializeObject(new { secureContent }); return secureRequest; } private SecuredContent CreateSecuredContent(string publicKeyXml, string request) { using (AesCryptoServiceProvider aesCsp = new AesCryptoServiceProvider()) { aesCsp.Mode = CipherMode.CBC; aesCsp.Padding = PaddingMode.PKCS7; aesCsp.BlockSize = 128; aesCsp.KeySize = 256; using (ICryptoTransform crt = aesCsp.CreateEncryptor(aesCsp.Key, aesCsp.IV)) { using (MemoryStream outputStream = new MemoryStream()) { using (CryptoStream encryptStream = new CryptoStream(outputStream, crt, CryptoStreamMode.Write)) { byte[] encodedRequest = Encoding.UTF8.GetBytes(request); encryptStream.Write(encodedRequest, 0, encodedRequest.Length); encryptStream.FlushFinalBlock(); byte[] encryptedRequest = outputStream.ToArray(); using (RSACryptoServiceProvider crp = new RSACryptoServiceProvider()) { crp.FromXmlstring(publicKeyXml); byte[] encryptedKey = crp.Encrypt(aesCsp.Key, false); return new SecuredContent() { Key = Convert.ToBase64string(encryptedKey), Iv = Convert.ToBase64string(aesCsp.IV), Content = Convert.ToBase64string(encryptedRequest) }; } } } } } } } ## Support Questions about using the Paylocity API? Please contact webservices@paylocity.com. # Deductions (v1) Deductions API provides endpoints to retrieve, add, update and delete deductions for a company's employees. For schema details, click here. # OnBoarding (v1) Onboarding API sends employee data into Paylocity Onboarding to help ensure an easy and accurate hiring process for subsequent completion into Web Pay. For schema details, click here.

GOV.UK Pay API (This version is no longer maintained. See openapi/publicapi_spec.json for latest API specification)

OTP email verification API by PayPI.

EmailVerify provides a simple way to verify email addresses. We send emails ourselves taking the burden of setting up email systems and tracking codes.

To learn more about this API, check out [EmailVerify documentation](https://emailverify.paypi.dev/)

## Authentication All requests to the EmailVerify API must be authenticated with an API Key. To get an API key, subscribe to the EmailVerify [here](https://app.paypi.dev/subscribe/c2VydmljZTo1OGQxZDNmMy05OWQ5LTQ3ZjYtOWJkNi02OWNkMTY1OGFmOWU=). \ Set your `Authorization` header to `Bearer YOUR-API-KEY`. ``` curl -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR-API-KEY" \ ... ```

Open, scableable, transparent payroll API.

PDF Blocks is a secure, reliable, and fast API to work with PDF documents. Actions include: Merge PDF documents, add or remove passwords, add watermarks, remove, extract, reverse, and rotate pages, and more.

PdfBroker.io is an api for creating pdf files from Xsl-Fo or Html and other useful pdf utilities.

# Introduction PDF Generator API allows you easily generate transactional PDF documents and reduce the development and support costs by enabling your users to create and manage their document templates using a browser-based drag-and-drop document editor. The PDF Generator API features a web API architecture, allowing you to code in the language of your choice. This API supports the JSON media type, and uses UTF-8 character encoding. You can find our previous API documentation page with references to Simple and Signature authentication [here](https://docs.pdfgeneratorapi.com/legacy). ## Base URL The base URL for all the API endpoints is `https://us1.pdfgeneratorapi.com/api/v3` For example * `https://us1.pdfgeneratorapi.com/api/v3/templates` * `https://us1.pdfgeneratorapi.com/api/v3/workspaces` * `https://us1.pdfgeneratorapi.com/api/v3/templates/123123` ## Editor PDF Generator API comes with a powerful drag & drop editor that allows to create any kind of document templates, from barcode labels to invoices, quotes and reports. You can find tutorials and videos from our [Support Portal](https://support.pdfgeneratorapi.com). * [Component specification](https://support.pdfgeneratorapi.com/en/category/components-1ffseaj/) * [Expression Language documentation](https://support.pdfgeneratorapi.com/en/category/expression-language-q203pa/) * [Frequently asked questions and answers](https://support.pdfgeneratorapi.com/en/category/qanda-1ov519d/) ## Definitions ### Organization Organization is a group of workspaces owned by your account. ### Workspace Workspace contains templates. Each workspace has access to their own templates and organization default templates. ### Master Workspace Master Workspace is the main/default workspace of your Organization. The Master Workspace identifier is the email you signed up with. ### Default Template Default template is a template that is available for all workspaces by default. You can set the template access type under Page Setup. If template has "Organization" access then your users can use them from the "New" menu in the Editor. ### Data Field Data Field is a placeholder for the specific data in your JSON data set. In this example JSON you can access the buyer name using Data Field `{paymentDetails::buyerName}`. The separator between depth levels is :: (two colons). When designing the template you don’t have to know every Data Field, our editor automatically extracts all the available fields from your data set and provides an easy way to insert them into the template. ``` { "documentNumber": 1, "paymentDetails": { "method": "Credit Card", "buyerName": "John Smith" }, "items": [ { "id": 1, "name": "Item one" } ] } ``` * * * * * # Authentication The PDF Generator API uses __JSON Web Tokens (JWT)__ to authenticate all API requests. These tokens offer a method to establish secure server-to-server authentication by transferring a compact JSON object with a signed payload of your account’s API Key and Secret. When authenticating to the PDF Generator API, a JWT should be generated uniquely by a __server-side application__ and included as a __Bearer Token__ in the header of each request. ## Legacy Simple and Signature authentication You can find our legacy documentation for Simple and Signature authentication [here](https://docs.pdfgeneratorapi.com/legacy). ## Accessing your API Key and Secret You can find your __API Key__ and __API Secret__ from the __Account Settings__ page after you login to PDF Generator API [here](https://pdfgeneratorapi.com/login). ## Creating a JWT JSON Web Tokens are composed of three sections: a header, a payload (containing a claim set), and a signature. The header and payload are JSON objects, which are serialized to UTF-8 bytes, then encoded using base64url encoding. The JWT's header, payload, and signature are concatenated with periods (.). As a result, a JWT typically takes the following form: ``` {Base64url encoded header}.{Base64url encoded payload}.{Base64url encoded signature} ``` We recommend and support libraries provided on [jwt.io](https://jwt.io/). While other libraries can create JWT, these recommended libraries are the most robust. ### Header Property `alg` defines which signing algorithm is being used. PDF Generator API users HS256. Property `typ` defines the type of token and it is always JWT. ``` { "alg": "HS256", "typ": "JWT" } ``` ### Payload The second part of the token is the payload, which contains the claims or the pieces of information being passed about the user and any metadata required. It is mandatory to specify the following claims: * issuer (`iss`): Your API key * subject (`sub`): Workspace identifier * expiration time (`exp`): Timestamp (unix epoch time) until the token is valid. It is highly recommended to set the exp timestamp for a short period, i.e. a matter of seconds. This way, if a token is intercepted or shared, the token will only be valid for a short period of time. ``` { "iss": "ad54aaff89ffdfeff178bb8a8f359b29fcb20edb56250b9f584aa2cb0162ed4a", "sub": "demo.example@actualreports.com", "exp": 1586112639 } ``` ### Signature To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that. The signature is used to verify the message wasn't changed along the way, and, in the case of tokens signed with a private key, it can also verify that the sender of the JWT is who it says it is. ``` HMACSHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), API_SECRET) ``` ### Putting all together The output is three Base64-URL strings separated by dots. The following shows a JWT that has the previous header and payload encoded, and it is signed with a secret. ``` eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhZDU0YWFmZjg5ZmZkZmVmZjE3OGJiOGE4ZjM1OWIyOWZjYjIwZWRiNTYyNTBiOWY1ODRhYTJjYjAxNjJlZDRhIiwic3ViIjoiZGVtby5leGFtcGxlQGFjdHVhbHJlcG9ydHMuY29tIn0.SxO-H7UYYYsclS8RGWO1qf0z1cB1m73wF9FLl9RCc1Q // Base64 encoded header: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 // Base64 encoded payload: eyJpc3MiOiJhZDU0YWFmZjg5ZmZkZmVmZjE3OGJiOGE4ZjM1OWIyOWZjYjIwZWRiNTYyNTBiOWY1ODRhYTJjYjAxNjJlZDRhIiwic3ViIjoiZGVtby5leGFtcGxlQGFjdHVhbHJlcG9ydHMuY29tIn0 // Signature: SxO-H7UYYYsclS8RGWO1qf0z1cB1m73wF9FLl9RCc1Q ``` ## Testing with JWTs You can create a temporary token in [Account Settings](https://pdfgeneratorapi.com/account/organization) page after you login to PDF Generator API. The generated token uses your email address as the subject (`sub`) value and is valid for __5 minutes__. You can also use [jwt.io](https://jwt.io/) to generate test tokens for your API calls. These test tokens should never be used in production applications. * * * * * # Libraries and SDKs ## Postman Collection We have created a [Postman](https://www.postman.com) Collection so you can easily test all the API endpoints wihtout developing and code. You can download the collection [here](https://app.getpostman.com/run-collection/329f09618ec8a957dbc4) or just click the button below. [](https://app.getpostman.com/run-collection/329f09618ec8a957dbc4) ## Client Libraries All our Client Libraries are auto-generated using [OpenAPI Generator](https://openapi-generator.tech/) which uses the OpenAPI v3 specification to automatically generate a client library in specific programming language. * [PHP Client](https://github.com/pdfgeneratorapi/php-client) * [Java Client](https://github.com/pdfgeneratorapi/java-client) * [Ruby Client](https://github.com/pdfgeneratorapi/ruby-client) * [Python Client](https://github.com/pdfgeneratorapi/python-client) * [Javascript Client](https://github.com/pdfgeneratorapi/javascript-client) We have validated the generated libraries, but let us know if you find any anomalies in the client code. * * * * * # Error codes | Code | Description | |--------|--------------------------------| | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found | | 422 | Unprocessable Entity | | 500 | Internal Server Error | ## 401 - Unauthorized | Description | |-------------------------------------------------------------------------| | Authentication failed: request expired | | Authentication failed: workspace missing | | Authentication failed: key missing | | Authentication failed: property 'iss' (issuer) missing in JWT | | Authentication failed: property 'sub' (subject) missing in JWT | | Authentication failed: property 'exp' (expiration time) missing in JWT | | Authentication failed: incorrect signature | ## 403 - Forbidden | Description | |-------------------------------------------------------------------------| | Your account has exceeded the monthly document generation limit. | | Access not granted: You cannot delete master workspace via API | | Access not granted: Template is not accessible by this organization | | Your session has expired, please close and reopen the editor. | ## 404 Entity not found | Description | |-------------------------------------------------------------------------| | Entity not found | | Resource not found | | None of the templates is available for the workspace. | ## 422 Unprocessable Entity | Description | |-------------------------------------------------------------------------| | Unable to parse JSON, please check formatting | | Required parameter missing | | Required parameter missing: template definition not defined | | Required parameter missing: template not defined |

The machine learning service APIs utilize hashtags from Twitter to find related, trending shows, related Twitter hashtags in real time and to generate direct tune-in URLs.

## Who is this for? This documentation is for developers creating their own integration with [Feedback's](https://www.pendo.io/product/feedback/) API. If you are doing a standard integration, there's a really easy [Javascript integration](https://help.receptive.io/hc/en-us/articles/209221969-How-to-integrate-Receptive-with-your-app) that you should know about before you go to the effort of building your own integration. ## Authentication API calls generally need to be authenticated. Generate an API Key at https://feedback.pendo.io/app/#/vendor/settings?section=integrate. This key should then be added to every request as a request header named 'auth-token' (preferred), or as a query parameter named 'auth-token'. ## Endpoint API endpoint is https://api.feedback.eu.pendo.io / https://api.feedback.us.pendo.io depending where your datacenter is located. ## Notes API endpoints are being added to this documentation as needed by customers. If you don't see an endpoint you need please contact support and if it exists we'll publish the docs here. The 'try it out' feature on this documentation page will probably be blocked by your browser because the Access-Control-Allow-Origin header has its value set by the Feedback server depending on your hostname. ## Generating client code This documentation is automatically generated from an OpenAPI spec available [here](http://apidoc.receptive.io/receptive.swagger.json). You can use Swagger to auto-generate API client code in many languages using the [Swagger Editor](http://editor.swagger.io/#/)

Self Service Developer API documentation and demo. ##Getting Started You will need an API access profile user and password in order to access search endpoints. Your access profile user and password is used for authenticating all requests to our search API. You MUST pass the user and password each time you perform a search request.

Personio Authentication API

API for reading and writing personnel data incl. data about attendances and absences

Random User Generator + OpenID Connect Provider. Like Lorem Ipsum, but for user accounts and authentication. The PhantAuth API documentation is available on the following API documentation sites: - [apiary](https://phantauth.docs.apiary.io) (primary source) - [speca](https://speca.io/phantauth/phantauth) - [PhantAuth Developer Portal](https://www.phantauth.net/api) ### TL;DR **PhantAuth was designed to simplify testing for applications using OpenID Connect authentication by making use of random generated users.** endpoint | address --------- | ------- issuer | https://phantauth.net discovery | https://phantauth.net/.well-known/openid-configuration credential | value ------------- | ----- client_id | test.client client_secret | UTBcWwt5 ## OpenID Connect The OpenID Connect Provider of PhantAuth supports the flows listed in the OpenID Connect specifications (Hybrid, Implicit, Authorization Code), as well as the Resource Owner Password grant type, specified in the OAuth 2.0 specifications. PhantAuth as an OpenID Connect Provider can be integrated with a variety of web applications, mobil applications, and backend applications. The integration can be either direct, as in the case of the OpenID Connect Provider, or through an authentication integration service, as in the case of Auth0 or Azure Active Directory B2C. To learn more, please go to chapter [Integration](https://doc.phantauth.net/#/integration). Examples: - [Direct OpenID Connect integration](https://www.phantauth.net/test/oidc) - [Auth0 Social Connections integration](https://www.phantauth.net/test/auth0) - [Azure Active Directory B2C integration](https://www.phantauth.net/test/azure) ## Random User The random user generator of PhantAuth can also be used separately, independent of the OpenID Connect Provider. You can generate an optional number of test users. In the knowledge of their user name, the data of the generated users can be regenerated at any time (OpenID Connect *sub* claim). The generated users have a unique, operational, disposable email address, a profile picture selected from one of the multiple pools of pictures, and the usual profile data. Custom email addresses and profile pictures may also be added. The random user generator of PhantAuth can be fully customized. Additionally, you can link an external generator to the application. For details,please go to chapter [Generator](https://doc.phantauth.net/#/generator). Test pages: - [Default Generator Test Page](https://phantauth.net/test/user) (embedded generator) - [Greek Gods Generator Test Page](https://phantauth.net/_gods/test/user) (embedded generator working from a Google Sheet) - [Faker Generator Test Page](https://phantauth.net/_faker/test/user) (external generator using Javascript Faker library) - [Chance Generator Test Page](https://phantauth.net/_chance/test/user) (external generator using Javascript Chance library) - [Casual Generator Test Page](https://phantauth.net/_casual/test/user) (external generator using Javascript Casual library) - [Randomuser Generator Test Page](https://phantauth.net/_randomuser/test/user) (client side generator using https://randomuser.me) - [uinames Generator Test Page](https://phantauth.net/_uinames/test/user) (client side generator using https://uinames.com) - [Mockaroo Generator Test Page](https://phantauth.net/_mockaroo/test/user) (client side generator using https://mockaroo.com) Every random generated user has a profile page, which contains their profile data in a simple one-page format. Profile examples: - [Random Profile](https://phantauth.net/%7Ejoe.black) - [Random Greek God Profile](https://phantauth.net/_gods/%7Ezeus) - [Random Faker Profile](https://phantauth.net/_faker/%7Eharry.houdini) - [Random Chance Profile](https://phantauth.net/_chance/%7Epeter.pan) - [Random Casual Profile](https://phantauth.net/_casual/%7Ejohn.smith) ## CodeSandbox The use of the random user generator and the direct integration of the OpenID Connect is demonstrated through a set of CodeSandbox samples. The sample applications are run directly from CodeSandbox, so the source code is easy to view, edit, and test. Examples: - [Random User Generator usage exampe](https://4xyj8lw394.codesandbox.io/) - [OpenID Connect direct integration exampe](https://8z77681269.codesandbox.io/) ## Tenants The PhantAuth is extremely versatile and customizable. You can use your own random user service, or generate users from an external .csv file or Google Sheet. You can use a set of Bootstrap themes to tailor the look and feel of the profile, morover, you can fundamentally change the same look and feel by the use of your own HTML templates. To find out more, please go to chapter [Tenant](https://doc.phantauth.net/#/tenant). To customize the application, you need to use one or more so-called tenants. A tenant can be consiered as an independent PhantAuth service. A tenant has its own random user generator endpoints and OpenID Connect endpoints. The tenants can be organised into so-called domains. Practically, a domain is a DNS zone, which contains the settings of the given tenant(s). The tenants as well as the domain can be configured by the use of DNS TXT records. In addition to the default tenant, the PhantAuth domain contains some sample tenants, which are primarily designed to demonstrate customizability, a range of hosting possibilities, and the links to external services. In most cases, using the [default tenant](https://phantauth.net) is enough. - [PhantAuth Default](https://phantauth.net) - default tenant, based on a Java Fairy library - [Greek Gods](https://phantauth.net/_gods) - based on a Google Sheet document - [PhantAuth Faker](https://phantauth.net/_faker) - based on a Javascript Faker library, hosted at https://now.sh - [PhantAuth Chance](https://phantauth.net/_chance) - based on a Javascript Chance library, hosted at https://now.sh - [PhantAuth Casual](https://phantauth.net/_casual) - based on a Javascript Casual library, hosted at https://webtask.io - [RANDOM USER](https://phantauth.net/_randomuser) - based on https://randomuser.me service - [uinames](https://phantauth.net/_uinames) - based on https://uinames.com service - [Mockaroo](https://phantauth.net/_mockaroo) - based on https://mockaroo.com service Anyone can create a domain and the tenants. Sharing the tenants is facilitated by the [PhantAuth Shared Domain](https://shared.phantauth.net). A shared domain is connected to the [phantauth.cf](http://phantauth.cf) DNS zone, where anyone can create tenant configuration nodes by the use of the [FreeDNS](https://freedns.afraid.org/) service. ### Concept The internal structure of PhantAuth is modular enough to allow certain elements to be customized or even replaced. The customized PhantAuth instances can be considered as separate services, which are independent from the original one. For the sake of simplicity, the customized PhantAuth instances will be called **tenants**. The customized PhantAuth instances (tenants) have a different URL from that of the default tenant. For technological and cloud hosting purposes, it is advised that only the beginning of the path component of these URLs differs from the default PhantAuth URL. Similarly, the path component of a tenant URL should start with a low line character ("_"). So the general format of a tenant URL is: ``` https://phantauth.net/_TENANT ``` where `TENANT` is the name of the tenant. The tenant name is a DNS domain name at the same time, which may lack `.phantauth.net` or `.phantauth.cf` from the end. ### DNS for configuration When desiging PhantAuth, the aim is that PhantAuth can run without a database, and it is configurable by the users. This can be achieved if for the purpose of storing the tenant configuration, the system uses the special TXT records of the Domain Name System (DNS), in compliance with the [RFC 6763](https://tools.ietf.org/html/rfc6763) specifications. So the tenant name is one or more DNS TXT records. These TXT records contain the configuration properties in NAME=VALUE format. This allows anyone to create their own tenants by creating a DNS domain and the TXT records in that domain. [Freenom](https://www.freenom.com), a service provider, allows you to register some top-level domains (.tk, .ml, .ga, .cf, .gq) free charge. The domain registered this way can be managed on the online interface of Freenom or transferred to an other free service provider offering a more convenient DNS name server (e.g. [CloudFlare](https://www.cloudflare.com/)). Additionally, [FreeDNS](https://freedns.afraid.org/) allows you to create DNS records within a second- or third level domain that is privately owned or shared with a community. In this case, you are advised to create the entries within the `phantauth.cf` domain, because here you can omit the `.phantauth.cf` from the tenant name in the URL. This means that a tenant with a name of `mytenant.phantauth.cf` can be referred to in the shorther `https://phantauth.net/_mytenant` format, rather than the longer `https://phantauth.net/_mytenant.phantauth.cf` URL . Similar to `.phantauth.cf`, the `phantauth.net` can be omitted, thus the officially supported and the example tenants can be referred to by their short names (e.g. https://phantauth.net/_faker). In a nutshell, to create a tenant, you have the following options: - With TXT records in a domain registered at Freenom, either on the online interface of Freenom or that of another free DNS service provider (e.g. CloudFlare). - With TXT records created in a second- or third level domain shared with a community, by using FreeDNS. - With TXT records created in your own existing DNS domain, by the use of an any DNS software. ### Parameters The below table contains a summary of the tenant parameters having an effect on the operation of the tenants. Property | Description --- | --- [name](#name) | the displayed name of the tenant [flags](#flags) | generator flags having an effect on the login page [theme](#theme) | the address of the Bootstrap theme [template](#template) | the address of the HTML page templates [factory](#factory) | the address of the external user generator [depot](#depot) | the address of the external user database [sheet](#sheet) | the identifier of the Google Sheets document containing the user database [script](#script) | the JavaScript URL inserted in the HTML pages [summary](#summary) | a one-line summary of the tenant [about](#about) | a detailed description of the tenant [attribution](#attribution) | the specifications of the external source [logo](#logo) | the logo of the tenant [favicon](#favicon) | the favicon of the tenant's web pages #### name The displayed name of the tenant is defined in the `name` parameter. In lack of such a name, the tenant's DNS name is displayed. This name appears in the address bar of the tenant's webpages. #### flags This parameter contains the flags that affect the operation of a tenant (see [Flags](generator.md#flags)). Currently, the flags affecting the team size are used in the login screen. If any of the flags is a team size flag, you can select the user from a list in the login screen, rather than using an input field. It can take the following values: - tiny - small - medium - large #### theme The HTML page templates of a tenant are created by the use of the Bootstrap library. This allows you to customize the layout and the colours of the pages by using external Bootstrap CSS files. The `theme` parameter contains the URL of the Bootstrap CSS file used in the pages. It is optional; in lack of such a parameter, the tenant's HTML pages have the default layout provided in the [PhantAuth developer portal](https://www.phantauth.net). #### template The place of the HTML page templates of a tenant is specified by the `template` parameter. The value of the parameter is n [RFC 6570 - URI temaplate](https://tools.ietf.org/html/rfc6570) expression. The URI template receives the page name in a `resource` parameter. The default value of the `template` parameter: ``` https://default.phantauth.net{/resource} ``` The `resource` URI template parameter may take the following values: Value | Description --- | --- tenant.html | the tenant's webpage; it contains a short description and the entry points of the tenant user.html | the user's profile page login.html | the login page used for signing in consent.html | the content page used for signing in team.html | the profile page of the user group client.html | the profile page of a client fleet.html | the profile page of the client group policy.html | the client's privacy policy tos.html | a client's terms of service test.html | a login test page of the user generator and OpenID Connect If you use your own template, the pages are fully customizable. The templates use a template engine called [Thymeleaf](https://www.thymeleaf.org/), which provides flexible template options. The source of the default template is available in the [phantauth-default](https://github.com/phantauth/phantauth-default) GitHub repository. If you wish to create your own templates, you are advised to produce them from these templates. #### factory PhantAuth allows you to use your own random resource (user, team) generator. To do so, you need to provide its address in the `factory` tenant parameter. The value of the parameter is an [RFC 6570 - URI temaplate](https://tools.ietf.org/html/rfc6570) expression. The URI template receives the type of the object (user, team) to be generated in the `kind` parameter, and the identifier of the object to be generated in the `name` parameter. #### factories In the `factories` parameter, you can specify the resource types that can be generated by the external generator set in the `factory` parameter. It takes the value of one or more strings from the following: `user`, `team`. #### depot Instead of generating a user and team resource, you can randomly select them from a pre-created inventory. In this case, the URL of the CSV file containing the resources can be specified in the `depot` parameter. The value of the parameter is an [RFC 6570 - URI temaplate](https://tools.ietf.org/html/rfc6570) expression. The URI template receives the type of the object (user, team) to be generated in the `kind` parameter. The first line of the CSV file contains the resource property names, the following lines, on the other hand, contain the relevant data. In the case of nested properties, a "." character separates the elements of the property name (e.g. address.formatted). #### depots In the `depots` parameter, you can specify the purpose of the external source set in the `depot` parameter. It takes the value of one or more strings from the following: `user`, `team`. #### sheet You can randomly select the user data from a Google Sheets document. In the `sheet` parameter, you can specify the identifier of a public Google Sheets document. The first row of the table contains the user property names, the following rows contain the relating data. In the case of nested properties, a "." character is used to separate the elements of the property name (e.g. address.formatted). The tenant named `gods` is an example for the use of the `sheet` parameter. It provides the user data in a [public Google Sheets](https://docs.google.com/spreadsheets/d/1Xa4mRcLWroJr2vUDhrJXGBcobYmpS8fNZxFpXw-M9DY/) document. In this case, the identifier of the sheet is `1Xa4mRcLWroJr2vUDhrJXGBcobYmpS8fNZxFpXw-M9DY`, and the associated TXT record is: ``` gods 120 IN TXT "sheet=1Xa4mRcLWroJr2vUDhrJXGBcobYmpS8fNZxFpXw-M9DY" ``` #### script You can automatically insert a custom JavaScript file in the login.html, consent.html, and test.html pages. The URL of this file can be specified in the `script` parameter. By inserting a custom JavaScript file, you can also integrate a client-side random user generator. #### summary You can provide a short, one-line description, a watchword for the tenant in the `summary` parameter. It appears on the tenant's startup page and all the pages that contain a list of available tenants. #### about To provide a detailed description of the tenant, use the `about` parameter. If it takes the value of a URL, the description is downloaded from the given URL; otherwise the value is the description itself. The description may have markdown formatting. #### attribution It is an external data source. If you use a random user generator, you can specify the attribution in the `attribution` parameter. The attribution may have markdown formatting, that is, you can highlight any element or provide a link to an external source: ``` randomuser 120 IN TXT "attribution=User data generated using [RANDOM USER GENERATOR](https://randomuser.me/)." ``` #### logo It is the URL of the tenant's logo. The image at this address appears in the address bar of the tenant's webpages. #### favicon Use the `favicon` parameter to provide the URL of the favicon. The image at this address appears as a shortcut icon in the browser when a user visits the tenant's webpages. ### Examples PhantAuth offers several examples for creating a custom tenant. They are ready-to-use tenants, although primarily created to show examples for customization. #### faker A [PhantAuth Faker](https://phantauth.net/_faker) tenant contains a generator built on the JavaScript Faker library. The generator runs on the serverless deployment platform of [ZEIT Now](https://now.sh), available free of charge. Its source code is accessible in the [phantauth-faker](https://github.com/phantauth/phantauth-faker) GitHub repository. Its DNS configuration is: ``` faker.phantauth.net. 120 IN TXT "factories=team" faker.phantauth.net. 120 IN TXT "factories=user" faker.phantauth.net. 120 IN TXT "flags=small" faker.phantauth.net. 120 IN TXT "factory=https://phantauth-faker.now.sh/api{/kind,name}" faker.phantauth.net. 120 IN TXT "userinfo=Dream Team" faker.phantauth.net. 120 IN TXT "theme=https://stackpath.bootstrapcdn.com/bootswatch/4.2.1/united/bootstrap.min.css" faker.phantauth.net. 120 IN TXT "logo=https://phantauth-faker.now.sh/faker-logo.svg" faker.phantauth.net. 120 IN TXT "name=PhantAuth Faker" ``` #### chance A [PhantAuth Chance](https://phantauth.net/_chance) tenant contains a generator built on the JavaScript Chance library. The generator runs on the serverless deployment platform of [ZEIT Now](https://now.sh), available free of charge. Its source code is accessible in the [phantauth-chance](https://github.com/phantauth/phantauth-chance) GitHub repository. Its DNS configuration is: ``` chance.phantauth.net. 120 IN TXT "flags=small" chance.phantauth.net. 120 IN TXT "name=PhantAuth Chance" chance.phantauth.net. 120 IN TXT "factory=https://phantauth-chance.now.sh/api{/kind,name}" chance.phantauth.net. 120 IN TXT "factories=team" chance.phantauth.net. 120 IN TXT "factories=user" chance.phantauth.net. 120 IN TXT "theme=https://stackpath.bootstrapcdn.com/bootswatch/4.2.1/united/bootstrap.min.css" chance.phantauth.net. 120 IN TXT "logo=https://phantauth-chance.now.sh/chance-logo.png" ``` #### casual A [PhantAuth Casual](https://phantauth.net/_casual) tenant contains a generator built on the JavaScript Casual library. The generator runs on the serverless deployment platform of [Auth0 Webtask](https://webtask.io), available free of charge. Its source code is accessible in the [phantauth-casual](https://github.com/phantauth/phantauth-casual) GitHub repository. Its DNS configuration is: ``` casual.phantauth.net. 120 IN TXT "logo=https://www.phantauth.net/logo/phantauth-logo-gray.svg" casual.phantauth.net. 120 IN TXT "name=PhantAuth Casual" casual.phantauth.net. 120 IN TXT "factory=https://wt-51217f7b3eee6aead0123eeafe3b83e8-0.sandbox.auth0-extend.com/user{?name}" casual.phantauth.net. 120 IN TXT "theme=https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" ``` #### gods For the [Greek Gods](https://phantauth.net/_gods) tenant, the user data is contained in a [public Google Sheets](https://docs.google.com/spreadsheets/d/1Xa4mRcLWroJr2vUDhrJXGBcobYmpS8fNZxFpXw-M9DY/) document. Its DNS configuration is: ``` gods.phantauth.net. 120 IN TXT "attribution=God pictures come from [Theoi Project](https://www.theoi.com/), a site exploring Greek mythology and the gods in classical literature and art." gods.phantauth.net. 120 IN TXT "name=Greek Gods" gods.phantauth.net. 120 IN TXT "flags=medium" gods.phantauth.net. 120 IN TXT "theme=https://stackpath.bootstrapcdn.com/bootswatch/4.2.1/sandstone/bootstrap.min.css" gods.phantauth.net. 120 IN TXT "logo=https://cdn.staticaly.com/favicons/www.theoi.com" gods.phantauth.net. 120 IN TXT "sheet=1Xa4mRcLWroJr2vUDhrJXGBcobYmpS8fNZxFpXw-M9DY" ``` #### randomuser The [RANDOM USER](https://phantauth.net/_randomuser) tenant uses the popular https://randomuser.me service to generate random users. The randomuser.me service is called on the client side, the call is contained in the [randomuser.js](https://www.phantauth.net/selfie/randomuser.js) script given in the `script` parameter. Its DNS configuration is: ``` randomuser.phantauth.net. 120 IN TXT "attribution=User data generated using [RANDOM USER GENERATOR](https://randomuser.me/)." randomuser.phantauth.net. 120 IN TXT "script=https://www.phantauth.net/selfie/randomuser.js" randomuser.phantauth.net. 120 IN TXT "flags=small" randomuser.phantauth.net. 120 IN TXT "name=RANDOM USER" randomuser.phantauth.net. 120 IN TXT "logo=https://cdn.staticaly.com/favicons/randomuser.me" randomuser.phantauth.net. 120 IN TXT "theme=https://stackpath.bootstrapcdn.com/bootswatch/4.2.1/sandstone/bootstrap.min.css" ``` #### uinames The [uinames](https://phantauth.net/_uinames) tenant uses the https://uinames.com service to generate random users. The uinames.com service is called on the client side, the call is contained in the [uinames.js](https://www.phantauth.net/selfie/uinames.js) script given in the `script` parameter. Its DNS configuration is: ``` uinames.phantauth.net. 120 IN TXT "attribution=User data generated using [uinames.com API](https://uinames.com)." uinames.phantauth.net. 120 IN TXT "logo=https://uinames.com/assets/img/ios-precomposed.png" uinames.phantauth.net. 120 IN TXT "flags=small" uinames.phantauth.net. 120 IN TXT "theme=https://stackpath.bootstrapcdn.com/bootswatch/4.2.1/minty/bootstrap.min.css" uinames.phantauth.net. 120 IN TXT "name=uinames" uinames.phantauth.net. 120 IN TXT "script=https://www.phantauth.net/selfie/uinames.js" ``` #### mockaroo The [Mockaroo](https://phantauth.net/_mockaroo) tenant uses the https://mockaroo.com service to generate random users. The mockaroo.com service is called on the client side, the call is contained in the [mockaroo.js](https://www.phantauth.net/selfie/mockaroo.js) script given in the `script` parameter. Its DNS configuration is: ``` mockaroo.phantauth.net. 120 IN TXT "attribution=User data generated using [Mockaroo's Mock APIs](https://mockaroo.com/mock_apis)." mockaroo.phantauth.net. 120 IN TXT "script=https://www.phantauth.net/selfie/mockaroo.js" mockaroo.phantauth.net. 120 IN TXT "logo=https://www.phantauth.net/selfie/kongaroo.svg" mockaroo.phantauth.net. 120 IN TXT "flags=small" mockaroo.phantauth.net. 120 IN TXT "theme=https://stackpath.bootstrapcdn.com/bootswatch/4.2.1/minty/bootstrap.min.css" mockaroo.phantauth.net. 120 IN TXT "name=Mockaroo" ``` ## Pricing PhantAuth is a free, open-source, non-profit application. If you find this service useful and can afford, please make a small donation as a contribution to the operation costs (domain registration, service hosting, etc.) [Donate on Ko-fi](https://ko-fi.com/Q5Q0T7C7) | [Donate on Liberapay](https://liberapay.com/szkiba/donate) | [Donate on PayPal](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=VXLCJ3EZRAE7G&source=url) ## Generator The basic concept of PhantAuth is that it generates data in a random but deterministic way. To achieve this goal, a so-called pseudorandom number generator (PRNG) is used. Each object type has an identifier (login name for user, client_id for client, etc.) By using a given hash algorithm, the value of the pseudorandom generator seed is produced from this identifier. Then, every property of the given object is generated with the pseudorandom generator started from this seed value. Taking advantage of the special feature of the pseudorandom number generator, also called as deterministic random bit generator (DRBG), that is, it generates the same random value series started from the same seed, the identifier clearly defines the object generated from it. That is, by the use of an identifier and generator, you can regenarate the properties of a given object at any time. Based on the above concept, PhantAuth is absolutely stateless, and no storage medium is necessary. So, a randomly selected login name will "exist", and the properties of the "associated" user can be generated. ### Identifier In brief, an object is defined by its identifier. The name of the identifier of a user or client object is `sub` or `client_id` used in the OpenID Connect specifications. The name of the identifier property of other PhantAuth-specific objects that are not included in the specifications is `sub`. The identifier may contain any character. ### Customization Sometimes you may want to customize the properties generated from the identifier. Although the identifier may contain any character, and its structure is optional, you can customize the generated values if a certain structure is used. #### Flags You can use a variety of flags to customize or give the parameters of certain object properties (user, client, etc.). The flags can be grouped by their effect on the generation of the properties. Basically, a flag is a keyword. You can set more than one flags to affect the generation of a variety of properties at the same time. To separate the flags from one another and the rest of the identifier, you need to use a semicolon `;`: ``` joe;female;kitten ``` In the above example, the user generated by the user generator is female, and her avatar is a randomly selected sketched kitten avatar. The other features are deterministically generated from the name "joe", that is, their values are not affected by the two flags. The [profile page](https://phantauth.net/%7Ejoe%3bfemale%3bkitten) of this example can be found [here](https://phantauth.net/%7Ejoe%3bfemale%3bkitten). Please note that the flags form part of the identifier, as a different flag allows you to generate a different object. ##### User gender flags The following flags modify the gender of the generated user. Flag | Description --- | --- male | The `gender` property of the generated user is male, independent of the user's name female | The `gender` property of the generated user is female, independent of the user's name guess | The `gender` property is defined on the basis of the generated user's given name (default) nogender | The generated user doesn't have a `gender` property ##### User avatar flags The following flags modify the generated avatar image. Avatar | Flag | Description --- | --- | ---  | ai | [AI](https://thispersondoesnotexist.com/) type generated, photo-like avatars (default)  | sketch | sketched photo-like [avataaars](https://getavataaars.com/) avatars  | photo | photo avatars  | dice | pixel art-style [DiceBear](https://github.com/DiceBear/avatars) avatars  | kitten | [ROBOHASH](https://robohash.org/)-generated sketched kitten avatars  | adorable | [Adorable Avatars](http://avatars.adorable.io/)  | mp | simple, cartoon-style silhouetted outline of a person (does not vary by user)  | identicon | a geometric pattern based on an email hash  | monsterid | a generated "monster" with different colors, faces, etc.  | wavatar | generated faces with varying features and backgrounds  | retro | awesome generated, 8-bit arcade-style pixelated faces  | robohash | a generated robot with different colors, faces, etc.  | blank | a transparent PNG image   | notfound | return an HTTP 404 (File Not Found) response   | noavatar | the user will not have a `picture` property ##### Client logo flags The following flags modify the generated logo. Logo | Flag | Description --- | --- | ---  | icon | [Game-icons.net](https://game-icons.net/) icon as a logo (default)  | fractal | [Electric Sheep](https://electricsheep.org/) fractal as a logo ##### `Group` size flags The following flag modify the sizes of the generated team (group of users) and fleet (group of clients). Flag | Size --- | --- tiny | 5 (default) small | 10 medium | 25 large | 50 huge | 100 #### Name In most cases, the generated objects have a full name, which is generated from the identifier. Instead of being generated, the full name can be produced from the identifier, if the identifier contains at least one period (`.`) or space (` `) character. In such cases, these characters play the role of separator between the parts of the full name (e.g. family name, given name). That is, the full name isn't randomly generated from the identifier but, by taking the separator characters into account, it is produced from the single parts of the full name (with capitalised initial letters). For this purpose, it is advised to use a period character, rather than a space character. ``` joe.black;sketch ``` In the above example: The full name of the user generated by the user generator is *Joe Black* (and his avatar is a skecthed profile avatar). The [profile page](https://phantauth.net/%7Ejoe.black%3bsketch) of this example can be found [here](https://phantauth.net/%7Ejoe.black%3bsketch). #### Picture In most cases, the generated objects have an image (avatar for a user, logo for a client), which is generated from the identifier. The *flags* determine which pre-defined inventory the image comes from (see [flags](#flags)). It can be further customized by the use of [Gravatar](https://gravatar.com). Each object has a generated unique email address (`email` for a user, `logo_email` for any other objects). To customize the image of a given object, you need to assign the gravatar image to this email address. By default, an object has a gravatar image, and the generated image is the default value of the gravatar URL only. In other words, as soon as you create a gravatar image to a given email address, that image will appear as the image associated with the given object. #### Email A disposable, operational email address suitable for receiving incoming emails is generated to each object. You can use your own email address (e.g. a previously set test email address) instead of a generated email address, if you prefer. In this case, the identifier contains an email address. Consequently, the image associated with the given object is the gravatar image assigned to the email address contained in the identifier. ``` ivan.test.szkiba@spam4.me ``` In the above example: The email address of the user generated by the user generator is *ivan.test.szkiba@spam4.me* (and his name is *Ivan Test Szkiba*). The [profile page](https://phantauth.net/%7Eivan.test.szkiba%40spam4.me) of this example can be found [here](https://phantauth.net/%7Eivan.test.szkiba%40spam4.me). ### Custom Generators PhantAuth can use external data sources and generators as well. The only restriction is that the external generator has to be deterministic. This means that even if called several times, it has to generate the same object to the same identifier. A special case of external generators is if an external data source is used. In such cases, the properties of a given object can be provided in a comma separated value (CSV) file or a Google Sheets document. The external data sources and generators can be defined by the use of so-called [tenants](https://doc.phantauth.net/#/tenant). To learn more, please go to chapter [Tenant](https://doc.phantauth.net/#/tenant).