Skip to main content

Bifrost Authentication Service

Bifrost is an authentication service that enables secure communication between external applications and the Sourceful Energy App (SEA). It serves as a bridge that facilitates safe authentication without requiring users to install external wallets on multiple devices.

Security by Design: Bifrost only handles public keys, never private keys. All private keys remain securely within either the SEA or the external application, ensuring that sensitive cryptographic material is never exposed to the bridge service.

Key Features​

  • Delegated Authentication: Allows third-party applications to authenticate via SEA to access the Sourceful Energy API as the authenticated user
  • No External Wallet Requirements: Users don't need to install external wallets on all devices
  • Secure Session Management: Short-lived sessions with explicit user approval
  • JWT-based Authentication: Signed tokens for authenticated API access
  • Zero Private Key Exposure: Only public keys are transmitted through Bifrost, with private keys remaining securely within their respective applications

Authentication Flow​

Session Lifecycle​

  1. Session Creation: External application generates a private key and sends its public key to Bifrost
  2. Session Validity: Sessions are valid for a maximum of 3 minutes
  3. User Approval: During this time, the user must approve the session in SEA
  4. Token Issuance: Upon approval, a signed JWT is returned to the external application
  5. API Access: The JWT can then be used for authentication with the Sourceful Energy API

JWT Token Structure​

JWT tokens issued by Bifrost follow this structure:

Header:

{
  "alg": "Ed25519",
  "typ": "JWT"
}

Payload:

{
  "created": "2025-04-28T08:50:41Z",
  "expiration": "2025-04-28T20:50:41Z",
  "issuer": "Bygcy876b3bsjMvvhZxghvs3EyR5y6a7vpvAp5D62n2w",
  "delegatedKey": "AWyXK19172kDydraqvqo1sAHpEBmPC81yxWsGFnShQbc"
}

Where:

  • issuer: The user's public key whose corresponding private key signs the JWT in SEA
  • delegatedKey: The public key of the external application whose generated private key can be used to sign messages

In an application it makes sense to show the issuer public key so the user understands what wallet is logged in, but at the same time make it clear that this is a JTW token based authentication. It does not make sense to show the delegatedKey as this is only used internally in the application and JWT token. Also note that the expiration time can be changed, as of now the default time to live is 12h.

Future Enhancements​

The JWT structure allows for extensibility. In future versions, additional fields can be added to the payload to provide fine-grained access rights, enabling more nuanced permission controls. The time to live can also be customized by either the protocl or the user in future versions.

Security Considerations​

While JWT token authentication provides improved user experience and security compared to exporting private keys, it still presents potential phishing risks:

  • An attacker could generate a session and send a deep link to a user
  • If the user approves the authentication request, the attacker could gain access

To mitigate these risks, Bifrost implements:

  1. Short Session Timeouts: Sessions expire after 3 minutes
  2. Limited JWT Validity: Tokens have a specified time-to-live
  3. Transfer Gateway Protection: The transfer gateway mutation does not accept JWT authentication
  4. Private Key Separation: Private keys never leave their origin applications:
    • External application's private key remains in the external application
    • User's private key remains in the SEA
    • Bifrost only handles public keys and signed tokens

API Endpoints​

Create Session​

Creates a new authentication session for key exchange between an external application and SEA.

  • URL: /api/auth
  • Method: POST
  • Request Body:
    {
      "delegatedKey": "5LubpwhZzwkKW49a2b5GwfFJdep1xtMDsuVeMGeBvJfx"
    }
  • Response:
    {
      "session_url": "https://example.com/auth/session/abcd1234",
      "session_id": "abcd1234"
    }

Get Session​

Retrieves the current state of a session.

  • URL: /api/auth/{session_id}
  • Method: GET
  • Response:
    {
      "delegatedKey": "5LubpwhZzwkKW49a2b5GwfFJdep1xtMDsuVeMGeBvJfx",
      "expiresAt": 1619654400,
      "token": "eyJhbGciOiJFZDI1NTE5IiwidHlwIjoiSldUIn0..."
    }

Delete Session​

Explicitly deletes a session before it expires.

  • URL: /api/auth/{session_id}
  • Method: DELETE
  • Response:
    {
      "status": "success"
    }

Implementation Example​

API Documentation​

The full OpenAPI documentation is available at:

https://bifrost.srcful.dev/docs