go-ring

go-ring

A Go client for Ring authentication, device discovery and controls, recordings, notifications, and live sessions. Ring behavior can vary by account, device, and region.

Requires Go 1.24 or later.

go get github.com/portpowered/go-ring@latest

Authenticate

Create a login session, request a verification code, and complete the exchange. The caller supplies the current access token with each account request.

client, err := ring.NewClient()
if err != nil {
    return err
}
login, err := client.NewLoginSession(ring.LoginSessionRequest{
    Username: username,
    Password: password,
})
if err != nil {
    return err
}
defer login.Close()

if err := login.Request2FACode(ctx); err != nil {
    return err
}
tokens, err := login.Authenticate(ctx, ring.CompleteLoginRequest{
    OTPCode: os.Getenv("RING_OTP_CODE"),
})
if err != nil {
    return err
}
auth := ring.AuthContext{
    AccessToken: tokens.AccessToken,
    HardwareID:  login.HardwareID(),
}

See the authentication guide for token refresh and secure token storage.

List devices

Use the same authentication context for device requests.

devices, err := client.ListDevices(ctx, ring.ListDevicesRequest{Auth: auth})
if err != nil {
    return err
}
for _, device := range devices.Devices {
    fmt.Printf("%s: %s (%s)\n", device.ID, device.Name, device.Kind)
}

The device operations guide covers controls, capabilities, and device-specific behavior.

Open a live session

Create a WebRTC offer with your peer connection, then pass it to the client. The returned answer belongs to that same peer. Close the session and signaling connection when finished.

conn, err := client.OpenSignaling(ctx, ring.OpenSignalingRequest{Auth: auth})
if err != nil {
    return err
}
defer conn.Close()

session, err := conn.StartDeviceSession(ctx, ring.StartDeviceSessionRequest{
    DeviceID:     deviceID,
    Offer:        ring.SessionDescription{Type: ring.SDPTypeOffer, SDP: offer.SDP},
    VideoEnabled: true,
    ICEMode:      ring.ICENonTrickle,
})
if err != nil {
    return err
}
defer session.Close()

answer := session.Answer()
if err := peer.SetRemoteDescription(webrtc.SessionDescription{
    Type: webrtc.SDPTypeAnswer,
    SDP:  answer.SDP,
}); err != nil {
    return err
}

See the live sessions guide for complete WebRTC and ICE setup, and the PTZ example for camera movement and stop commands.

More examples

Documentation

• Customer guides cover authentication, configuration, devices, recordings, notifications, live sessions, and playback.
• Generated API reference documents the client and its request and result types.
• Diagnostic CLI guide introduces the optional go-ring command-line tool.

Issues and license

Please open an issue for a reproducible bug or unsupported device behavior. go-ring is licensed under Apache-2.0; see LICENSE.