MT-23076: support api token expiration

README.md

@@ -86,7 +86,7 @@ Account & organization management:
 - Accounts — list the accounts a token can access — [`examples/accounts`](examples/accounts)
 - Account accesses — list & remove user/invite/token access — [`examples/account-accesses`](examples/account-accesses)
 - Permissions — list resources & bulk-update access permissions — [`examples/permissions`](examples/permissions)
-- API token management — list, create, get, reset & delete — [`examples/api-tokens`](examples/api-tokens)
+- API token management — list, create, get, reset & delete, with optional token expiration — [`examples/api-tokens`](examples/api-tokens)
 - Billing — current billing-cycle usage across Sandbox, Sending & Marketing — [`examples/billing`](examples/billing)
 - Organization sub-accounts — list & create — [`examples/sub-accounts`](examples/sub-accounts)
 

account_accesses.go

@@ -44,14 +44,15 @@ type AccountAccess struct {
 
 // AccountAccessSpecifier describes the entity that holds the access. Which
 // fields are set depends on the specifier type: users and invites carry Email,
-// while API tokens carry AuthorName, Token, and ExpiresAt.
+// while API tokens carry AuthorName, Token, MaskedToken, and ExpiresAt.
 type AccountAccessSpecifier struct {
 	ID                             int64  `json:"id"`
 	Email                          string `json:"email,omitempty"`
 	Name                           string `json:"name,omitempty"`
 	TwoFactorAuthenticationEnabled *bool  `json:"two_factor_authentication_enabled,omitempty"`
 	AuthorName                     string `json:"author_name,omitempty"`
 	Token                          string `json:"token,omitempty"`
+	MaskedToken                    string `json:"masked_token,omitempty"`
 	ExpiresAt                      string `json:"expires_at,omitempty"`
 }
 

api_tokens.go

@@ -2,6 +2,7 @@ package mailtrap
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"net/http"
 )
@@ -37,13 +38,54 @@ type APITokenPermission struct {
 	AccessLevel int `json:"access_level"`
 }
 
+// TokenExpiration is an optional token expiration as an RFC 3339 date-time.
+// Leave the request field nil for the server default (a 1-year default is
+// being rolled out). Use NeverExpires for a token that never expires. Past or
+// more-than-5-years-ahead values are rejected with 422. It is a request-only
+// type: responses report the expiry as the plain APIToken.ExpiresAt string.
+type TokenExpiration struct {
+	value string
+	never bool
+}
+
+// ExpiresAt returns a token expiration at the given RFC 3339 date-time, e.g.
+// "2027-06-01T00:00:00Z". An empty string is sent as "" and rejected by the
+// server; leave the request field nil to omit the expiration instead.
+func ExpiresAt(rfc3339 string) *TokenExpiration {
+	return &TokenExpiration{value: rfc3339}
+}
+
+// NeverExpires returns a token expiration for a token that never expires. It
+// serializes as an explicit "expires_at": null.
+func NeverExpires() *TokenExpiration {
+	return &TokenExpiration{never: true}
+}
+
+// MarshalJSON encodes the RFC 3339 date-time, or null for NeverExpires.
+func (e TokenExpiration) MarshalJSON() ([]byte, error) {
+	if e.never {
+		return []byte("null"), nil
+	}
+	return json.Marshal(e.value)
+}
+
 // CreateAPITokenRequest is the payload for creating an API token. Name is
 // required.
 type CreateAPITokenRequest struct {
-	Name      string                `json:"name"`
+	Name string `json:"name"`
+	// ExpiresAt is the optional token expiration. Nil omits the field and
+	// applies the server default; see TokenExpiration.
+	ExpiresAt *TokenExpiration      `json:"expires_at,omitempty"`
 	Resources []*APITokenPermission `json:"resources,omitempty"`
 }
 
+// ResetAPITokenRequest is the optional payload for resetting an API token.
+type ResetAPITokenRequest struct {
+	// ExpiresAt is the optional expiration of the replacement token. Nil omits
+	// the field and applies the server default; see TokenExpiration.
+	ExpiresAt *TokenExpiration `json:"expires_at,omitempty"`
+}
+
 // List returns all API tokens visible to the current token.
 func (s *APITokensService) List(ctx context.Context) ([]*APIToken, *Response, error) {
 	var tokens []*APIToken
@@ -70,10 +112,19 @@ func (s *APITokensService) Create(ctx context.Context, req *CreateAPITokenReques
 
 // Reset expires the token and issues a replacement with the same permissions.
 // The returned token's Token field holds the new value; store it securely.
-func (s *APITokensService) Reset(ctx context.Context, tokenID int64) (*APIToken, *Response, error) {
+// req is optional: pass nil to send no request body and apply the server
+// default expiration. Resetting a token that has already expired is rejected
+// with 422.
+func (s *APITokensService) Reset(ctx context.Context, tokenID int64, req *ResetAPITokenRequest) (*APIToken, *Response, error) {
 	path := fmt.Sprintf("/api/api_tokens/%d/reset", tokenID)
+	// Assign req to any only when non-nil: a typed nil pointer would encode as
+	// a literal null body instead of sending no body at all.
+	var body any
+	if req != nil {
+		body = req
+	}
 	token := new(APIToken)
-	resp, err := s.client.do(ctx, HostGeneral, http.MethodPost, path, nil, nil, token)
+	resp, err := s.client.do(ctx, HostGeneral, http.MethodPost, path, nil, body, token)
 	return token, resp, err
 }
 

api_tokens_test.go

@@ -2,12 +2,29 @@ package mailtrap_test
 
 import (
 	"context"
+	"encoding/json"
+	"errors"
+	"io"
 	"net/http"
+	"strings"
 	"testing"
 
 	"github.com/mailtrap/mailtrap-go"
 )
 
+// wantRawBody fails the test unless r's body is exactly want, proving whether
+// the expires_at key is absent, null, or a string on the wire.
+func wantRawBody(t *testing.T, r *http.Request, want string) {
+	t.Helper()
+	b, err := io.ReadAll(r.Body)
+	if err != nil {
+		t.Fatalf("read request body: %v", err)
+	}
+	if got := strings.TrimSpace(string(b)); got != want {
+		t.Errorf("request body = %q, want %q", got, want)
+	}
+}
+
 func TestAPITokens_List(t *testing.T) {
 	mux, client := setup(t)
 	mux.HandleFunc("GET /api/api_tokens", func(w http.ResponseWriter, _ *http.Request) {
@@ -44,7 +61,7 @@ func TestAPITokens_Get(t *testing.T) {
 func TestAPITokens_Create(t *testing.T) {
 	mux, client := setup(t)
 	mux.HandleFunc("POST /api/api_tokens", func(w http.ResponseWriter, r *http.Request) {
-		wantJSONBody(t, r, `{"name":"My API Token","resources":[{"resource_type":"account","resource_id":3229,"access_level":100}]}`)
+		wantRawBody(t, r, `{"name":"My API Token","resources":[{"resource_type":"account","resource_id":3229,"access_level":100}]}`)
 		_, _ = w.Write([]byte(`{"id":12345,"name":"My API Token","token":"a1b2c3d4e5f6"}`))
 	})
 
@@ -62,13 +79,111 @@ func TestAPITokens_Create(t *testing.T) {
 	}
 }
 
+func TestAPITokens_Create_expiresAt(t *testing.T) {
+	mux, client := setup(t)
+	mux.HandleFunc("POST /api/api_tokens", func(w http.ResponseWriter, r *http.Request) {
+		wantRawBody(t, r, `{"name":"My API Token","expires_at":"2027-06-01T00:00:00Z"}`)
+		_, _ = w.Write([]byte(`{"id":12345,"name":"My API Token","expires_at":"2027-06-01T00:00:00Z","token":"a1b2c3d4e5f6"}`))
+	})
+
+	token, _, err := client.APITokens.Create(context.Background(), &mailtrap.CreateAPITokenRequest{
+		Name:      "My API Token",
+		ExpiresAt: mailtrap.ExpiresAt("2027-06-01T00:00:00Z"),
+	})
+	if err != nil {
+		t.Fatalf("Create: %v", err)
+	}
+	if token.ExpiresAt != "2027-06-01T00:00:00Z" {
+		t.Errorf("token = %+v", token)
+	}
+}
+
+func TestAPITokens_Create_neverExpires(t *testing.T) {
+	mux, client := setup(t)
+	mux.HandleFunc("POST /api/api_tokens", func(w http.ResponseWriter, r *http.Request) {
+		wantRawBody(t, r, `{"name":"My API Token","expires_at":null}`)
+		_, _ = w.Write([]byte(`{"id":12345,"name":"My API Token","expires_at":null,"token":"a1b2c3d4e5f6"}`))
+	})
+
+	token, _, err := client.APITokens.Create(context.Background(), &mailtrap.CreateAPITokenRequest{
+		Name:      "My API Token",
+		ExpiresAt: mailtrap.NeverExpires(),
+	})
+	if err != nil {
+		t.Fatalf("Create: %v", err)
+	}
+	if token.ExpiresAt != "" {
+		t.Errorf("token = %+v", token)
+	}
+}
+
+func TestAPITokens_Create_expirationRejected(t *testing.T) {
+	mux, client := setup(t)
+	mux.HandleFunc("POST /api/api_tokens", func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusUnprocessableEntity)
+		// Expiration failures are record-level, so the API reports them under "base".
+		_, _ = w.Write([]byte(`{"errors":{"base":["Expiration date must be in the future"]}}`))
+	})
+
+	_, _, err := client.APITokens.Create(context.Background(), &mailtrap.CreateAPITokenRequest{
+		Name:      "My API Token",
+		ExpiresAt: mailtrap.ExpiresAt("2020-01-01T00:00:00Z"),
+	})
+	var ve *mailtrap.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("errors.As(*ValidationError) = false for %T", err)
+	}
+	if got := ve.Fields["base"]; len(got) != 1 || got[0] != "Expiration date must be in the future" {
+		t.Errorf("Fields[base] = %v", got)
+	}
+}
+
+func TestCreateAPITokenRequest_marshalExpiresAt(t *testing.T) {
+	tests := []struct {
+		name string
+		req  *mailtrap.CreateAPITokenRequest
+		want string
+	}{
+		{
+			name: "nil omits the key",
+			req:  &mailtrap.CreateAPITokenRequest{Name: "t"},
+			want: `{"name":"t"}`,
+		},
+		{
+			name: "NeverExpires writes explicit null",
+			req:  &mailtrap.CreateAPITokenRequest{Name: "t", ExpiresAt: mailtrap.NeverExpires()},
+			want: `{"name":"t","expires_at":null}`,
+		},
+		{
+			name: "ExpiresAt writes the date-time",
+			req:  &mailtrap.CreateAPITokenRequest{Name: "t", ExpiresAt: mailtrap.ExpiresAt("2027-06-01T00:00:00Z")},
+			want: `{"name":"t","expires_at":"2027-06-01T00:00:00Z"}`,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := json.Marshal(tt.req)
+			if err != nil {
+				t.Fatalf("Marshal: %v", err)
+			}
+			if string(got) != tt.want {
+				t.Errorf("Marshal = %s, want %s", got, tt.want)
+			}
+		})
+	}
+}
+
 func TestAPITokens_Reset(t *testing.T) {
 	mux, client := setup(t)
-	mux.HandleFunc("POST /api/api_tokens/12345/reset", func(w http.ResponseWriter, _ *http.Request) {
+	mux.HandleFunc("POST /api/api_tokens/12345/reset", func(w http.ResponseWriter, r *http.Request) {
+		wantRawBody(t, r, "")
+		if ct := r.Header.Get("Content-Type"); ct != "" {
+			t.Errorf("Content-Type = %q, want empty", ct)
+		}
 		_, _ = w.Write([]byte(`{"id":12345,"name":"My API Token","token":"newtoken123"}`))
 	})
 
-	token, _, err := client.APITokens.Reset(context.Background(), 12345)
+	token, _, err := client.APITokens.Reset(context.Background(), 12345, nil)
 	if err != nil {
 		t.Fatalf("Reset: %v", err)
 	}
@@ -77,6 +192,42 @@ func TestAPITokens_Reset(t *testing.T) {
 	}
 }
 
+func TestAPITokens_Reset_expiresAt(t *testing.T) {
+	mux, client := setup(t)
+	mux.HandleFunc("POST /api/api_tokens/12345/reset", func(w http.ResponseWriter, r *http.Request) {
+		wantRawBody(t, r, `{"expires_at":"2027-06-01T00:00:00Z"}`)
+		_, _ = w.Write([]byte(`{"id":12345,"name":"My API Token","expires_at":"2027-06-01T00:00:00Z","token":"newtoken123"}`))
+	})
+
+	token, _, err := client.APITokens.Reset(context.Background(), 12345, &mailtrap.ResetAPITokenRequest{
+		ExpiresAt: mailtrap.ExpiresAt("2027-06-01T00:00:00Z"),
+	})
+	if err != nil {
+		t.Fatalf("Reset: %v", err)
+	}
+	if token.ExpiresAt != "2027-06-01T00:00:00Z" {
+		t.Errorf("token = %+v", token)
+	}
+}
+
+func TestAPITokens_Reset_neverExpires(t *testing.T) {
+	mux, client := setup(t)
+	mux.HandleFunc("POST /api/api_tokens/12345/reset", func(w http.ResponseWriter, r *http.Request) {
+		wantRawBody(t, r, `{"expires_at":null}`)
+		_, _ = w.Write([]byte(`{"id":12345,"name":"My API Token","expires_at":null,"token":"newtoken123"}`))
+	})
+
+	token, _, err := client.APITokens.Reset(context.Background(), 12345, &mailtrap.ResetAPITokenRequest{
+		ExpiresAt: mailtrap.NeverExpires(),
+	})
+	if err != nil {
+		t.Fatalf("Reset: %v", err)
+	}
+	if token.ExpiresAt != "" {
+		t.Errorf("token = %+v", token)
+	}
+}
+
 func TestAPITokens_Delete(t *testing.T) {
 	mux, client := setup(t)
 	mux.HandleFunc("DELETE /api/api_tokens/12345", func(w http.ResponseWriter, _ *http.Request) {

examples/api-tokens/main.go

@@ -6,6 +6,7 @@ import (
 	"log"
 	"os"
 	"strconv"
+	"time"
 
 	"github.com/mailtrap/mailtrap-go"
 )
@@ -29,6 +30,9 @@ func main() {
 
 	token, _, err := client.APITokens.Create(ctx, &mailtrap.CreateAPITokenRequest{
 		Name: "CI token",
+		// Omit ExpiresAt for the server default expiration, or pass
+		// mailtrap.NeverExpires() for a token that never expires.
+		ExpiresAt: mailtrap.ExpiresAt(time.Now().AddDate(0, 0, 30).Format(time.RFC3339)),
 		Resources: []*mailtrap.APITokenPermission{
 			{ResourceType: mailtrap.ResourceTypeAccount, ResourceID: accountID, AccessLevel: mailtrap.AccessLevelViewer},
 		},
@@ -37,14 +41,17 @@ func main() {
 		log.Fatal(err)
 	}
 	// The full token value is only returned by Create and Reset — store it securely.
-	fmt.Printf("created token %d: %s\n", token.ID, token.Token)
+	fmt.Printf("created token %d (expires %s): %s\n", token.ID, token.ExpiresAt, token.Token)
 
 	if _, _, err = client.APITokens.Get(ctx, token.ID); err != nil {
 		log.Fatal(err)
 	}
 
 	// Reset expires the token and issues a replacement with the same permissions.
-	token, _, err = client.APITokens.Reset(ctx, token.ID)
+	// Pass nil instead of a request to apply the server default expiration.
+	token, _, err = client.APITokens.Reset(ctx, token.ID, &mailtrap.ResetAPITokenRequest{
+		ExpiresAt: mailtrap.NeverExpires(),
+	})
 	if err != nil {
 		log.Fatal(err)
 	}