Redirect URIs

A Redirect URI is a place on the client to which the server can redirect the user's browser after they have completed authentication. A client may have zero or more Redirect URIs associated with it. A client using the Authorization Code Flow will have at least one Redirect URI.

All Redirect URIs for a client must be registered with the server before they can be used. Contact us to have new Redirect URIs added or old Redirect URIs removed.

There are rules for which Redirect URIs we will accept. Rules for specific client types or situations override general rules.

A typical Redirect URI might look like:

https://app.yourdomain.example/callback

General Rules

1. Redirect URIs must match exactly when used as an argument. If the Redirect URI is registered with query parameters, those query parameters must match byte-for-byte when used as an argument. Similarly, if a port is specified it must match exactly.
2. A well-formed Redirect URI will have at least 3 slashes; "https://app.yourdomain.example/" is valid but "https://app.yourdomain.example" is not.
3. The "https://" scheme is strongly preferred over "http://"; additional justification may be required before an "http://" Redirect URI is configured.
4. Custom URL schemes are supported, such as "my_iracing_app://", to support mobile applications. We strongly prefer reversed domain names. If the application is associated with the domain "app.yourdomain.com" please use the scheme "example.yourdomain.app://" to avoid conflict.
5. Host names are strongly preferred over IP addresses. The exception for this is "localhost" where either "127.0.0.1" or "[::1]" is strongly preferred.
6. Port numbers may be specified. The Redirect URI "http://127.0.0.1:12345/callback" is valid.
7. Implicit ports may not used unless the Redirect URI is registered with an explicit port number. If the Redirect URI "https://app.yourdomain.example/callback" is registered, using "https://app.yourdomain.example:443/callback" as an argument will fail.
8. Any arbitrary path may be used. We prefer paths such as "/", "/callback", "/redirect", or "/login".
9. Parameters are allowed, but the parameters must match exactly. To use Redirect URIs such as "https://app.yourdomain.example/callback?flow=one" and "https://app.yourdomain.example/callback?flow=two" both must be registered.
10. There must be no fragment in the URL; "https://app.yourdomain.example/callback#fragment" is not allowed.

Native Application Support

To support native applications we allow Redirect URIs may also be formed like:

http://127.0.0.1:0/callback

1. The scheme MUST be "http://"
2. The host MUST be the IPv4 (127.0.0.1) or IPv6 ([::1]) loopback address; "localhost" or equivalents will not be accepted.
3. The port MUST be 0.
4. The other General Rules still hold.

A native application may:

1. start a web server bound to an ephemeral port on the loopback device;
2. wait for a callback on the web server in the background; then
3. start a web browser, or have the user start a browser, submitting a request to /authorize with a redirect_uri that substitutes 0 with the ephemeral port.

The redirect_uri that the client uses for /authorize might be something like "http://127.0.0.1:25417/callback" assuming the local web server is listening on port 25417.

When the user completes the Authentication and Authorization process the user's web browser will be redirected back to the web server bound on the ephemeral port. The code and state values may be collected. The web server can be shut down, and the client may invoke /token to finish the process.